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1  Overview 


Libremote  is  a  small  library  that  handles  remote  objects  through  the  use  of  callback  functions, 
which  are  a  component  of  ModSAF’s  method  of  event  handling.  Using  this  method,  libremote, 
the  library  that  is  interested  in  network  packets  belonging  to  remote  entities,  requests  that  the 
libcallback  library  tests  for  those  packet  receipt  events  (these  tests  are  coded  in  libpktvalve)  and 
then  calls  a  registered  libremote  function  when  the  event  happens. 

After  ModSAF  initialization  is  complete,  the  ModSAF  software  begins  its  normal  processing 
which  typically  includes  listening  for  packets  on  the  network.  When  the  libcallback  events  occur, 
the  software  generating  the  event  (libpktvalve)  passes  libcallback  the  event  handle  and  arguments; 
libcallback  then  calls  the  registered  libremote  callback  function.  With  this  method  libcallback 
distributes  event  information  from  a  low  layer  service  provider  (libpktvalve)  to  a  higher  layer 
library  (libremote). 

The  use  of  libcallback,  therefore,  maintains  the  relationship  between  two  libraries:  (1)  libpkt¬ 
valve  which  detects  vehicle  appearance,  deactivate,  designator,  and  stealth  packets;  and  (2)  libre¬ 
mote  which  filters  these  packets,  performs  relevant  actions  (such  as  creating  new  remote  vehicles 
via  libvtab  when  appropriate),  and  then  passes  the  packet  data  to  approbate  libraries  (such  as 
libentity,  libdesignate,  or  libstealth). 

Currently,  libremote  registers  the  following  callback  functions: 
racai vad.vapp() 

handles  update  or  creation  of  a  remote  vehicle  when  a  vehicle  appearance  packet  is 

received 

received.deact i vat e ( ) 

handles  removal  of  a  remote  vehicle  when  a  deactivate  packet  is  received 

racai vad.daa Ignat a ( ) 

handles  update  or  creation  of  a  designator  when  a  designate  packet  is  received 
racai  ved.stop.deaignataO 

handles  removal  of  a  designator  when  a  stop  designate  packet  is  received 
racai vad.sapp() 

handles  the  update  or  creation  of  a  remote  stealth  when  a  stealth  appearance  packet 

is  received 

When  the  vehicle  appearance  packet  for  a  remote  vehicle  (includes  DI),  missile,  or  structure 
(building  or  bridge)  is  received,  the  following  processing  takes  place  via  the  received.vappO 
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function. 

1.  Translate  the  packet’s  network  ID  to  a  local  computer  vehicle  id. 

2.  If  the  vehicle  does  not  already  exist,  determine  if  this  packet  refers  to  an  allowed  type  ( VTAB.REMOTE.VEHIC 
VTAB.REMOTE. MISSILE,  or  VTAB.REMOTE.STRUCTURE).  If  it  does  then  make  a  new  remote  ve¬ 
hicle  by  calling 

safobj_creata_raaote(vahicl«.id,  aim. id,  type ,  remote_tick_rate)  otherwise  exit. 

3.  If  this  packet  was  for  a  newly  created  remote  or  for  an  already  exisiting  remote,  pass  the  packet 
on  to  libentity  for  processing. 

When  the  deactivate  packet  for  a  remote  vehicle  (includes  DI),  missile,  or  structure  (building  or 
bridge)  is  received,  the  following  processing  takes  place  via  the  received.deactivateO  function. 

1.  Translate  the  packet’s  network  ID  to  a  local  computer  vehicle  id. 

2.  If  the  vehicle  does  not  already  exist,  exit. 

3.  If  this  packet  was  for  an  exisiting  remote  (not  local)  vehicle,  pass  the  packet  on  to  libentity 
for  processing. 

When  the  designate  packet  for  a  remote  designator  (includes  laser  beam),  is  received,  the  fol¬ 
lowing  processing  takes  place  via  the  received.designataO  function. 

1.  Translate  the  packet’s  network  ID  to  a  local  computer  vehicle  id. 

2.  If  the  vehicle  does  not  already  exist,  create  it  as  a  remote  designator  via  a  call  to: 

a alobj_create_remote( vehicle. id,  sia.id, 

VTAB. REMOTE. DESIGHATOR,  reaote.tick.rate) 

3.  Pass  the  packet  on  through  to  libdesignate  for  processing  via  the  function 
dsg_packet.received( vehicle. id ,  packet) . 

When  the  stop  designate  packet  for  a  remote  designator  (includes  laser  beam),  is  received,  the 
following  processing  takes  place  via  the  received.stop.designateO  function. 

1.  Translate  the  packet’s  network  ID  to  a  local  computer  vehicle  id. 

2.  If  the  vehicle  does  not  already  exist,  exit. 

3.  If  the  vehicle  is  classified  as  local  rather  than  remote,  exit. 

4.  Pass  the  packet  on  through  to  libdesignate  for  processing  via  the 
d8g.packet_r«ceivad(vehicle_id,  packet)  function. 

When  the  appearance  packet  for  a  remote  stealth  is  received,  the  following  processing  takes 
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place  via  the  received. sappO  function. 

1.  If  this  packet  does  not  refer  to  the  type  VTAfi.REMOTE.STEALTH,  exit. 

2.  Translate  the  packet’s  network  ID  to  a  local  computer  vehicle  id. 

3.  If  the  stealth  does  not  already  exist,  then  make  a  new  remote  vehicle  by  calling 
safobj _ create. remote ( vehicle. id,  sim_id,  type,  remote.tick.rate). 

4.  If  this  packet  was  for  a  newly  created  stealth  or  for  an  already  exisiting  stealth,  pass  the  packet 
on  to  libstealth  for  processing  via  the  function  steal th.appearance.receivedC vehicle. id, 
packet) . 
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2  Functions 


The  following  sections  describe  each  function  provided  by  libremote,  including  the  format  aiul 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  remoteJnit 


void  remote. init (packet. valve,  types,  tick_rate,  exercise.id, 
sim_addr,  protocol) 

PV.VALVE.PTR  packet. valve ; 

uint 16  types ; 

uint32  tick.rate ; 

uint8  exercise.id; 

SinulationAddress  *sim_addr; 
int32  protocol ; 


‘packet. valve’ 

Specifies  the  packet  valve  used  to  receive  packets  for  vehicles,  missiles,  structures, 
stealths,  and  designators. 

‘types’  Specifies  the  types  of  remotes  which  should  be  created. 

‘tick.rate’ 

Specifies  the  tick  rate  for  remote  vehicles. 

‘exercise.id’ 

Specifies  the  exercise  ID  to  listen  to. 

‘protocol’ 

Specifies  protocol  in  use  (0  for  SIMNET,  DIS.PROTOCOL. VERSION.*  for  DIS) 


remote. init  initializes  libremote.  This  function  installs  packet  handlers  for  remote  vehicle 
appearance  and  deactivate  packets,  types  specifies  the  types  of  vehicles  which  libremote  should 
create  (such  as  VTAB.REHOTE. VEHICLE  I  VTAB.REMOTE.STRUCTURE,  which  would  prevent  remote 
missiles  from  being  registered).  The  tick  rate  specifies  the  rate  at  which  remotes  should  be  ticked 
for  RVA  purposes  (note  that  RVA  will  not  necessarily  occur  every  tick;  see  libentity  for  more 
details).  The  exercise  ID  specifies  the  exercise  which  will  be  monitored  for  arriving  vehicles  (you 
can  change  this  after  init  time  via  a  call  to  pv.change.exercise  on  the  simulation? rotocolNumber, 
see  section  ‘pvjchangejexercise’  in  Libpktvalve  Programmer’s  Manual). 


When  libremote  creates  a  remote  vehicle,  it  automatically  includes  the  following  sub-classes: 
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•  entity 

•  pbtab 

Call  pvjnit  before  this  function.  See  section  ‘pvjnit’  in  Libpktvalve  Programmer’s  Manual. 
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3  Events 


The  following  sections  describe  each  event  provided  by  libremote. 


3.1  remote  Jocal_deactivated_event 

CALLBACK.EVENT.PTR  remote.local.deactivated.event ; 

I 

The  remote.local.deactivated.event  event  fires  when  a  local  vehicle  receives  a  deactivate 
packet  (which  under  DIS  2.0.3,  is  an  entity  state  packet  with  a  magic  bit  set). 


void  handler(vehicle.id) 
int32  vehicle. id; 
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1  Overview 


LibRouteMap  provides  a  convenient  interface  to  the  spatial  planning  algorithms  in  libMoveMap. 
The  library  creates  a  movemap  at  program  startup  which  contains  "large"  terrain  features  for  the 
whole  database.  Routines  can  preplan  courses  for  units  using  this  database. 

The  database  is  initialized  to  support  a  variety  of  unit  width  configuration  spaces.  When  a  call 
is  made  to  plan  a  route  through  the  database,  the  closest  width  which  is  greater  than  or  equal  to 
the  desired  width  is  used.  Each  additional  width  configurations  adds  to  the  storage  and  compute 
requirements. 
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2  Functions 


The  following  sections  describe  each  function  provided  by  libroutemap,  including  the  format 
and  meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  routemap  .create 


EOUTEMAP.PTR  routemap.createCetdb,  quad.p,  num. width*,  width,  width...) 
CTDB  *ctdb; 

QUAD. DATA  *quad_p; 
int32  nun. widths ; 

int32  width,  width. . . ; 


‘ctdb’  Specifies  the  CTDB  terrain  database 
‘quad.p’  Specifies  the  quadtree  terrain  database 
‘nun.  widths’ 

Specifies  the  number  of  unit  widths  to  generate  maps  for 
‘width,  width. . 

Specifies  unit  widths,  in  increasing  order 


routsaap.crsats  creates  a  routemap  for  a  terrain  database.  This  routemap  can  be  used  to 
plan  a  route  around  large  obstacles.  The  map  is  set  up  in  advance  to  support  planning  for  a  variety 
of  unit  widths.  The  width  used  for  a  particular  instance  of  planning  will  be  the  preplanned  width 
which  is  no  smaller  than  the  passed  unit  width.  The  widths  must  be  passed  in  increasing  order. 


2.2  routemap.preplan 


void  routsmap.prwplanCroutemap,  obs taels .mask,  max.millissconds, 

goal,  max_plan_dsviation,  unit .width,  plan) 
ROUTEMAP. PTR  routsaap ; 
uint32  obstaclo.mask; 

uint32  max.millissconds ; 

ROUTE. POINTS  *goal; 

float64  max.pl an. deviation; 

int32  unit. width; 

ROUTE.POINTS  *plan; 
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‘routenap’ 

Specifies  tbe  route  map 

‘obstacle.aask’ 

Specifies  the  obstacles  to  avoid 
‘max.milliseconds’ 

Specifies  the  maximum  time  to  spend  planning  the  route 
‘goal’  Specifies  the  goal  path 

‘max„plan_dsviation’ 

Specifies  the  maximum  deviation  allowed  around  each  obstacle 
‘unit.vidth’ 

Specifies  the  width  of  the  unit  which  will  execute  the  plan 
‘plan’  Returns  the  planned  route 

routemap.preplan  performs  obstacle  avoidance  around  fixed  obstacles  which  match  the  passed 
type  mask,  and  returns  the  shortest  course  which  can  be  found  in  the  specified  time.  The  returned 
plan  is  dynamically  allocated  using  HS_ROUTE_ALLOCATE_POIHTS  (from  ‘stdroute.h’),  and  thus 
plan. points  should  be  freed  using  5TDDEALL0C.  If  no  plan  can  be  found  within  the  allotted  time, 
plan.num.pts  with  be  0,  and  plan,  points  will  be  MULL. 

The  obstads.mask  should  be  an  inclusive  OR  of  the  following  flags: 

ROUTEMAP. RIVERS 

River  networks 
ROUTEMAP.LAKES 
Lakes 

ROUTEMAP.BOULDERS 

Boulder-covered  areas  which  are  specified  in  the  libquad  database 
ROUTEMAP. CANOPIES 

Tree  canopies 
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1  O  verview 


Librwa  implements  an  instance  of  the  hull  class  of  components.  It  provides  a  low  fidelity  model 
of  rotary  wing  vehicle  dynamics. 


1.1  Basic  Modes 

The  helicopter  has  two  basic  modes  of  flight,  depending  on  speed.  At  low  speed  (SLOW  mode), 
it  uses  the  rotor  only  and  can  face  in  any  direction.  It  maneuvers  by  tilting  the  rotor-vector.  At 
high  speed,  it  behaves  somewhat  like  a  fixed  wing  aircraft.  It  turns  by  flying  a  curving  route, 
rather  than  rotating  in  place.  It  may  either  keep  its  jets  horizontal  (FAST-HORIZONTAL  mode) 
or  aligned  with  the  velocity  vector  (FAST-ALIGNED  mode). 


1.2  Basic  Notation 

Vectors  are  represented  by  bold  letters.  Desired  values  have  hats.  Thus,  R  represents  the  rotor 
lift  vector,  '  R  represents  the  desired  rotor  lift  vector,  and  R  represents  the  scalar  amount  of  lift. 

When  a  vector  is  listed  in  terms  of  its  components,  it  is  enclosed  in  square  brackets.  Thus, 
R  =  [ft*,  ftp,  ft,] 

ft  The  3D  vector  indicating  the  direction  and  magnitude  of  the  lift/thrust  generated  by  the 
rotor.  It  points  out  through  the  drive  shaft  and  is  always  perpendicular  to  J. 

J  The  3D  vector  indicating  the  direction  and  magnitude  of  the  thrust  generated  by  the  jets.  It 
points  out  the  nose  of  the  helicopter  and  is  always  perpendicular  to  R. 

Tt  The  time-constant  for  a  generic  quantity  x,  which  can  be  R,  track  angle,  FPA,  etc. 

A  Either  the  track  angle  (0=East,  »/2=North)  or  the  reciprocal  of  a  time-constant,  as  will  be 
specified  in  each  context. 

7  Flight  path  angle,  or  FPA  (0  for  horizontal,  x/2  for  straight  up,  */2  for  straight  down). 

0  Roll  angle.  0  is  vertical,  -t-x/2  is  90  degrees  to  the  right,  -*/2  is  90  degrees  to  the  left. 
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V  The  3D  velocity  vector  indicating  the  direction  and  speed. 

V  The  scalar  speed  of  the  RWA 

D  The  3D  vector  indicating  the  direction  and  magnitude  of  the  drag  force.  For  notational 
convenience,  it  is  taken  to  point  along  the  velocity  vector,  not  opposite  to  it. 

g  The  3D  vector  indicating  the  direction  and  magnitude  of  the  gravitational  acceleration.  For 
notational  convenience,  it  is  taken  to  point  up  the  Z  axis,  not  opposite  to  it. 

M  The  instantaneous  mass  of  the  RWA. 


1.3  Dynamics  Model 

A  purely  vector  representation  was  chosen  to  avoid  singularities  associated  with  trigonometric 
representations.  Essential  singularities  (such  as  the  direction  of  a  O-vector)  persist,  but  those 
associated  purely  with  the  coordinate  system  (such  as  vertical)  are  eliminated.  A  single  dynamics 
model  is  used  for  the  entire  flight  regime,  regardless  of  the  speed  or  altitude.  It  simply  sums  the 
net  forces  of  drag,  gravity,  rotor  thrust,  and  jet  thrust  to  compute  the  overall  acceleration  of  the 
RWA’8  center  of  mass.  A  more  detailed  physics  model  of  the  orientational  dynamics  was  explored 
in  the  initial  formulation,  based  on  the  cyclic  variation  rotor  angle  of  attack  throughout  its  rotation 
and  the  thrust  of  the  tail  rotor.  Careful  examination  revealed  that,  with  an  optimal  controller,  the 
overall  dynamics  of  the  controlled  system  would  be  a  simply  second  order  vector  controller,  and  it 
was  implemented  as  such. 


1.3.1  Rotational  Dynamics 

The  rotational  dynamics  are  represented  by  the  control  of  the  jet  and  rotor.  The  physical 
dynamics  and  low  level  control  are  merged  into  a  simple  analytic  form,  capable  of  closed  form 
solution.  This  is  also  the  fastest  control  loop.  Using  a  closed  form  control  allows  much  longer  time 
steps  to  be  tolerated. 

This  section  will  describe  the  underlying  physics,  which  justifies  the  merging  of  dynamics  and 
control  into  a  low-level  model. 


Gyroscopic  dynamics  are  not  modeled,  as  a  reasonable  controller  would  set  its  controls  first  to 
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eliminate  gyroscopic  effects,  then  impose  the  desired  motion. 


1.3.2  Translational  Dynamics 
V*  V  ♦  dtA 

P’  ■:  P  ♦  dtV  ♦  (A  *  sqr(dt) )  /  2 

The  drag  function  has  linear  and  quadratic  terms  in  velocity,  and  depends  on  air  density,  and 
is  directed  along  the  velocity  vector. 


1.4  Control  Model 

There  are  four  basic  control  inputs:  the  3D  desired  flight  vector,  and  the  desired  azimuth  along 
which  the  body  should  lace.  (Of  course,  in  high-speed  mode,  the  actual  azimuth  is  along  the  flight 
vector.)  This  is  in  contrast  to  the  FWA  model  for  ModSAF,  which  has  three  basic  control  inputs, 
specifying  the  3D  desired  flight  vector.  The  additional  RWA  parameter  comes  from  the  decoupling 
of  azimuth-faced  from  direction  of  flight  at  low  speeds. 

There  are  two  basic  levels  of  control:  (a)  rotating  and  scaling  the  rotor  and  jet  thrust  vectors, 
to  meet  net-acceleration  goals,  and  (b)  setting  the  net-acceleration  to  meet  desired- velocity  goals. 
They  are  analytically  completely  independent,  and  are  implemented  and  described  as  such. 

For  testing,  a  third  layer  was  added  which  sets  desired- velocity  to  meet  route-following  goals. 


1.4.1  Rotational  Control 

Both  the  rotor  and  the  jet  are  modeled  as  second  order  critically  damped  vector  controllers. 
They  respond  to  the  user’s  commands  as  if  they  were  applied  in  continuous  time  through  a  zero 
order  hold.  Second  order  was  chosen  to  avoid  the  instanteous  speed  changes  associated  with  first 
order  controllers;  under-damping  was  rejected  by  the  requirement  to  avoid  oscillations;  critical 
damping  was  chosen  so  that  only  one  time-constant  is  needed. 

To  review  the  notation  of  a  second  order  controller,  assume  we  are  controlling  a  vector  quantity  X 


The  current  error  term  is: 
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epsilon  •  X  -  desired  X 
Because  the  control  is  exerted  through  a  ZOH: 
d  epsilon/dt  *  dX  /  dt 

The  following  algorithm  updates  the  second  order,  critically  damped  controller. 

C.l  ■  epsilon 
lambda  *  1  /  tau 

C_2  ■  d  epsilon  /  dt  ♦  lanbda  epsilon 

L  ■  C.l  ♦  dt  C.2 

d  ■  •‘(-lambda  dt) 

dX*  /  dt  -  (C.2  -  lambda  C.l)  d 

X'  »  dL  +  desired  X 

A  vector  controller  having  different  time-constants  for  different  components  is  quite  feasible, 
but  somewhat  less  compact  to  program.  One  involving  cross-coupling  between  components  would 
require  the  replacement  of  the  scalar  exponentials  above  with  matrix  exponentials,  at  greatly  in¬ 
creased  computational  cost. 


1.4.2  Translational  Control 

The  FAST  and  SLOW  modes  differ  greatly  in  how  they  do  turns.  In  SLOW  mode,  there  are 
two  options.  In  the  first  turning  option,  the  rotor  vector  is  simply  turned  so  as  to  accelerate  the 
helicopter  in  the  desired  direction.  Thus,  if  the  helicopter  is  heading  due  East  and  is  directed  to 
go  due  West,  it  will  turn  its  rotor  vector  backward  to  stop  its  eastward  motion,  hold  it  backward 
so  as  to  accelerate  to  the  westward,  then  straighten  up  the  rotor  vector  so  as  to  cruise  along  at 
the  desired  speed.  The  whole  maneuver  takes  place  with  no  North  or  South  excursions  at  all,  and 
there  is  no  rolling.  There  is  no  change  in  the  body  orientation  (i.e.  in  the  jet  vector  J  ),  as  the 
vehicle  can  maintain  any  desired  yaw  (though  roll  and  pitch  are  determined  by  the  desired  net 
acceleration).  That  is,  it  can  maintain  a  90  degree  yaw  in  flying  sideways,  or  a  180  degree  yaw  in 
flying  backwards. 
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The  second  option  of  SLOW  mode,  and  the  only  option  in  the  two  FAST  modes,  is  to  bank  to 
turn  as  an  airplane  would  do.  Thus,  the  180  degree  reversal  described  above  would  be  accomplished 
by  following  a  curving  path  off  to  the  North  or  South  (depending  on  which  direction  was  slightly 
less  than  180  degrees),  as  an  airplane  would  do. 

The  desired  net  acceleration  in  the  first  option  of  SLOW  mode  is  given  simply  by  the  following 
expression.  This  net  acceleration  can  only  be  achieved  in  SLOW  mode. 

desired  A  ■  (dasirad  V  -  V)  /  tau  V  (A) 

Thus,  changes  in  the  X,  Y,  and  Z  velocity  arc  treated  symmetrically,  except  in  that  HELO- LIMIT- 
FORCE-  VECTOR  will  clamp  the  force  vector  so  as  to  not  exceed  the  maximum  lift  currently 
generatable,  preserving  the  Z  component  if  possible.  This  is  done  so  as  to  make  terrain  avoid¬ 
ance/following  quite  response  in  the  very  low-altitude  regime  where  SLOW  mode  would  by  typically 
employed. 

In  the  second  SLOW  option  (only  one  in  FAST  mode)  the  track,  FPA,  and  Z  components  are 
treated  separately,  in  their  response  rates  and  the  qualitative  form. 

First,  the  Z  component  of  velocity  is  treated  as  a  first  order  controller.  In  a  classical  first-order 
controller,  one  sets 

desired  x  ■  x  +  tau  dx/dt, 

and  attempts  to  match  that  constant  rate  of  increase  which  would  take  one  to  the  goal  in  time 
r.  As  the  FPA  7  is  determined  by  the  Z  component  of  velocity  (divided  by  speed),  the  appropriate 
rate-constant  to  use  is  r,.  So  the  desired  acceleration  in  the  Z  direction  is  as  follows: 

desired  Az  ■  (desired  Az  -  Az)  /  tau  gamma 

Second,  the  (X,Y)  component  of  velocity  is  treated  as  a  kind  of  first  order  controller,  with  linear 
increase  in  magnitude  (as  with  a  one-dimensional  first  order  controller),  and  constant  rotation 
rate  (which  is  novel,  as  far  as  I  know).  Because  the  (X,Y)  direction  determines  track  angle,  the 
appropriate  rate-constant  for  turning  i>  .  Similarly,  speed  is  adjusted  using  t$  .  Considering  only 
the  (X,Y)  components  of  the  vector,  the  desired  behavior  of  steady  rotation  and  steady  scaling  is 
modeled  by  the  following  equation 

V(t)  ■  (a  +  bt) [cos(theta  ♦  t  caega) ,  sin( theta  ♦  t  omega)]  (B) 


6 


Librwa  Programmer’s  Guide 


Setting  (B)  to  give  V  at  t  =  0  and  * V  at  time  t  =  r  gives  the  desired  parameters,  and  so  determines 
the  (X,Y)  acceleration  desired. 


theta  »  tan“-l(Vy,  Vx) 

theta  *  t an" -1 (desired  Vy,  desired  Vx) 

osega  ■  ANGLE-DIFF  (desired  theta,  theta)  /  tau  lambda 

S  -  sqrt(Vy“2  ♦  Vx*2) 

desired  S  *  sqrt(desired  Vy"2  ♦  desired  Vx"2) 

b  ■  (desired  S  -  S)  /  tau  S  (C) 


The  function  ANGLE-DIFF  returns  acute  angle  difference,  so  as  to  always  turn  through  the 
smaller  angle. 


Differentiating  (B)  with  respect  to  time  gives  the  expression  for  the  X  and  Y  components  of  the 
desired  acceleration,  and  the  following  overall  expression: 


dssirsd  Ay  *  -omega  Vy  ♦  (b/S)  Vx 
desired  Ax  ■  omega  Vx  ♦  (b/S)  Vy 
desired  Az  *  desired  kz  -  kz  /  tau  gamma  (0) 


If  there  is  no  change  in  the  (X,Y)  speed,  then  6  ss  0  (D)  gives  an  acceleration  which  is  exactly 
perpendicular  to  the  (X,Y)  velocity,  i.e.  a  pure  rotation.  But  the  rate  of  rotation  declines  at  the 
angle  left  to  traverse  shrinks.  Similarly,  if  there  is  no  change  in  angle,  then  w  ss  0  and  (D)  gives 
an  acceleration  which  is  exactly  along  the  (X,Y)  velocity,  i.e.  a  pure  speed-up,  with  the  rate  of 
acceleration  declining  as  the  speed-gap  shrinks. 


It  is  worth  noting  that  (C)  and  (D)  are  the  key  functions  of  a  very  nonlinear  controller.  For  small 
angle  or  speed  changes,  it  is  essentially  linear,  while  for  large  changes  it  is  highly  nonlinear  but 
very  well  behaved. 


It  would  be  quite  feasible  to  use  (D)  to  determine  the  desired  net  acceleration  in  SLOW  mode  as 
well  as  FAST  mode,  if  smooth  turns  were  desired. 

This  is  a  fundamental  improvement  over  the  controller  which  this  author  produced  for  the 
ModSAF  fixed  wing  aircraft  dynamics.  In  the  FWA  controller,  lateral  motion  (track  and  roll)  were 
controlled  completely  independently  from  longitudinal  ones  (speed  and  FPA).  This  would  produce 
noticable  slowing  in  turns,  loss  of  altitude,  and  so  on.  All  these  problems  have  now  been  fixed,  as 
the  controller  above  looks  at  the  desired  speed  and  rotation  in  one  unified  operation,  so  it  correctly 
handles  combined  nonlinear  maneuvers. 
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The  desired  net  acceleration  is  then  used  in  a  force-balance  equation  to  determine  the  desired  ‘  R 
and  '  J  vectors.  Thus,  the  rotor  and  helicopter  forces  must  generate  a  net  force  which  will  cancel 
out  the  constant  gravitational  and  nonlinear  drag  forces,  then  in  addition  impose  the  desired  overall 
acceleration. 

desired  R  +  desired  J  ■  desired  F  ■  H  desired  A  ♦  Mg  ♦  D 

How  the  three  components  of  ‘F  are  split  up  between  '  R  and  '  J  is  what  determines  the  two  FAST 
modes. 

In  FAST-HORIZONTAL  mode,  the  jet  vector  (and  body  orientation)  is  kept  horizontal,  with  the 
rotor  vector  rotating  in  a  plane  perpendicular  to  it  as  the  RWA  rolls  one  way  or  another.  The 
horizontal  vector  pointing  along  V  is  given  by  the  following  expression: 

H  ■  g  cross  (V  cross  g) 

Then  "J  is  just  that  component  of  ~F  parallel  to  H  ,  while  '  R  is  the  component  which  is  perpen¬ 
dicular.  If  ‘  J  •  H  <  0  ,  then  the  ideal  motion  would  require  reverse  thrust,  which  is  not  possible, 
and  the  desired  thrust  vector  is  reset  to  a  zero-vector. 

In  FAST-ALIGNED  mode,  *  J  is  just  that  component  of  ~F  parallel  to  V  ,  while  ~R  is  the  component 
which  is  perpendicular. 

In  the  prototype  LISP  code,  there  is  a  global  variable  specifying  whether  or  not  inverted  flight  is 
allowed.  For  fast,  tight  terrain  following,  inversion  is  required  (as  how  F15  flip  when  crossing  ridge 
lines),  as  it  might  also  be  for  aerial  combat  between  RWA’s.  If  inversion  is  not  allowed,  then  the  Z 
component  of  'A  is  bounded  from  below  by  mg/ 10  ,  so  that  it  always  points  at  least  somewhat  up, 
and  the  RWA  never  dives  at  more  than  -0.9  G’s  acceleration. 

In  both  FAST  modes,  *  R  is  then  immediately  limited  to  what  the  rotor  can  currently  generate, 
preserving  the  Z  component  if  possible.  Thus,  it  will  make  a  slower  turn  if  necessary  to  maintain 
altitude,  and  will  only  pull  as  many  G’s  in  the  turn  as  it  is  physically  capable  of  generating.  The 
net  effect  in  both  modes  is  that  the  RWA  will  roll  over  to  a  specific  bank  angle,  hold  it  steady 
through  the  turn,  then  roll  out  at  the  end. 

Notice  that  the  only  way  to  rapidly  slow  down  is  to  tilt  the  rotor  backwards.  Hence,  if  one  tries 
to  approach  and  stop  at  a  point  (hovering  or  landing)  in  either  of  the  FAST  modes,  it  will  overshoot 
and  start  orbiting  the  point.  There  should  be  a  means  of  doing  an  automatic  mode  change  to  avoid 
this  problem,  and  to  provide  strong  forward  acceleration. 
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1.5  Limits  and  Clamping 
Limit  magnitude  of  R-hat  and  J-hat 

Retreating  blade  stalls  limit  the  RWA’s  forward  velocity.  This  dynamic  effect  is  not  modeled, 
as  the  low-level  controller  would  simply  not  request  a  velocity  over  that  limit.  This  needs  to  be 
put  in  as  a  user-limit  on  speed. 

Rate-limited  update  of  R-hat  and  J-hat 

Helo- bound-force- vector 

Rho  limits  on  lift 

User  limits  on  speed,  turn  rates,  FPA.  The  maximum  sustainable  FPA  was  computed,  as  it 
is  critical  for  FAST- ALIGNED  mode  (but  not  FAST-HORIZONTAL,  which  can  do  any  FPA, 
including  vertical  rise/fall). 


1.6  Calibration  and  Stability 

The  Comanche  is  reportedly  able  to  do  "snap  turns"  (i.e.  a  few  seconds  for  90  degrees)  at  up  to 
180  knots,  or  92.6  m/s.  [The  limitation  is  supposedly  retreating  blade  stall,  seeming  to  imply  that 
attempting  to  generate  that  much  lift,  with  the  low  relative  wind  over  the  retreating  blade,  gets  it 
right  to  the  edge  of  a  blade  stall.]  If  it  completes  90  degrees  in  5  seconds,  that  requires  a  few  G’s 
of  lateral  acceleration  and  one  to  stay  level,  implying  3.1  G’s  total  lift  to  complete  the  turn  level, 
with  no  loss  of  speed. 

As  an  example,  the  delivered  LISP  code  assumed  a  19,000  Kg  mass,  80,000  Newtons  of  jet 
thrust,  and  3.1  G’s  of  rotor  thrust.  The  drag  coefficient  is  set  at  16.49,  so  that  the  horizontal  flight 
in  FAST  mode  is  drag-limited  to  50%  more  than  the  above  corner  speed.  The  linear  and  quadratic 
components  of  drag  are  equal  at  84.5  m/s. 

Traditional  linear  control  theory  provides  some  guidance  as  to  what  will  be  stable  combinations 
of  parameters.  However,  the  presence  of  rate  limits,  magnitude  limits,  and  unpredictable  step 
length  all  contribute  to  render  a  full  nonlinear  stability  analysis  quite  difficult. 

Some  empirical  testing  and  observation  was  done  in  addition  to  formal  analysis. 
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Through  all  phases  of  development,  the  position  of  the  RWA  was  randomly  perturbed  by  up  to 
10cm  along  each  axis  at  each  tick,  in  an  attempt  to  excite  some  unstable  resonance.  No  problem 
was  ever  observed. 

For  testing  purposes,  a  simple  route-following  procedure  was  used,  in  which  the  RWA  aims  at  a 
point  ahead  of  itself,  a  certain  lead-distance  down  the  route.  Thus,  on  very  long  routes,  it  will 
rapidly  pull  onto  the  route,  then  follow  it  closely  the  rest  of  the  way,  rather  than  fly  a  very  slowly 
converging  straight  line  path  toward  the  final  end  point.  A  higher  level  controller  was  written  which 
sets  the  desired  velocity  ‘  V  to  be  the  position  error  divided  by  rp  =  2.5  seconds  in  SLOW  mode  and 
by  5.0  seconds  in  FAST  mode.  This  will  not  be  discussed  further,  as  it  was  purely  for  a  wrapper 
for  testing. 

With  rt i  ss  0.2  ,  tv  =  1.0  ,  tp  s  2.5  ,  and  a  maximum  rotor  lift  of  3.1  G’s,  the  SLOW  and  FAST 
modes  were  observed  to  be  stable  over  the  entire  range  of  conditions  described  below.  In  SLOW 
mode,  a  formal  analysis  can  be  done  to  show  that  the  eigenvalues  are  at  (-3.8312, -.5844  ±  0.4249,;') . 
This  corresponds  to  one  mode  with  a  time-constant  of  0.261  seconds,  and  two  decaying  oscillatory 
ones  with  a  time  constant  of  1.71  seconds  and  a  period  of  14.8  seconds.  Thus,  they  decay  into 
negligability  before  completing  even  a  small  fraction  of  a  cycle.  This  was  empirically  confirmed  by 
the  lack  of  overshoot  in  turning,  stopping  in  mid-air  to  hover,  and  landing  within  a  few  centimeters 

t 

of  a  designated  goal  point. 

If  the  max  G’s  is  limited  to  2,  then  with  the  third-level  control  algorithm  for  testing,  it  starts 
overshooting  in  the  Z  direction  because  it  can  not  generate  enough  force  to  pull  out  of  rapid  dives. 
Whether  or  not  this  occurs  in  the  final  ModSAF  application  depends  on  what  algorithms  are  used 
to  determine  V  ,  but  it  is  an  issue  to  be  aware  of.  Clearly,  looking  only  a  short  distance  ahead  will 
generally  require  larger  forces,  applied  more  rapidly,  to  acheive  the  desired  result  in  the  short  time 
available  -  and  limited  force  violates  that  assumption. 


Time  steps  were  randomly  varied  between  0.5  and  1.5  times  the  mean  time  step,  and  the  mean 
time  step  was  varied  from  0.05  seconds  to  0.75  seconds.  This  is  broader  than  the  requirements,  as 
the  maximum  update  rate  ModSAF  supports  is  1/16  second,  and  0.5  seconds  is  overload. 

The  effect  of  very  short  time  ticks  is  make  the  dynamics  and  control  behave  in  a  more  nearly  ideal 
and  continuous  fashion.  Short  ticks  do  not  cause  sluggish  response.  In  fact,  longer  ticks  cause  faster 
response  in  the  translational  modes.  For  example,  if  the  time  step  is  exactly  tau  V  and  equation 
(A)  is  used,  then  the  velocity  is  matched  exactly  in  one  time  step.  As  the  ticks  get  shorter,  a  more 
realistic  exponential  decay  is  observed.  If  the  ticks  are  slightly  longer  than  ry  ,  then  a  rapidly 
decaying  oscillation  is  observed.  When  the  ticks  get  out  to  1.5ry  ,  then  oscillations  are  being  halved 
in  magnitude  at  each  time  step.  In  this  calibration,  ry  =  1.0  ,  so  none  of  these  conditions  will  occur 
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until  the  system  is  well  past  its  overload  condition  of  0.5  second  time  steps. 
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2  Parameters 


Data  file  entry  should  read: 


(SM.RWAHull 

(min_fpa  <float>  degrees)  ; ;  minimum  dive  angle 

(vel.response.time  <float>  seconds)  ; ;  rate  of  response  when  not 

rate  limited 

(fpa.response.time  <float>  seconds)  ; ;  fpa  response  time  in  fast  mode 

(track.response.time  <float>  seconds)  ;;  respnse  time  in  fast  mode,  when 

not  g  limited 

(thrust. response. time  <float>  seconds)  ; ;  thrust  response  time  in  fast  mode 
(jet.response.time  <float>  seconds)  ; ;  rate  of  change  in  jet  thrust 

(rotor.response.time  <float>  seconds)  ; ;  rate  of  change  of  rotor  thrust 

(rtr.ctrl.resp.time  <float>  seconds)  ; ;  time  to  change  cntrl  setting 

(jet.ctrl.resp.time  <float>  seconds)  ; ;  time  to  change  cntrl  setting 

(mass  <f loat>  Kg)  ; ;  vehicle  snss 

(max. jet. thrust  <float>  Newtons)  ;;  max  jet  thrust  (assuming  vehicle 

has  a  jet) 

(inversion  <int>  True(l)/False(0))  ;;  is  inverison  allowed? 

(has. jet  <int>  True(l)/False(0))  ;;  does  this  have  a  jet? 

(max_rotate_rate  <float>  radians/sec)  ;;  maximum  controlled  rotating 

rate 

(max.gs  < float >  gravitys)  ; ;  max  Gs  the  airframe  can  pull 

(vel.cruise  <float>  metes/second)  ;;  cruise  velocity 

(vel_max  <float>  meters/second)  ; ;  max  foreward  velocity 

(vel.max.back  <float>  meters/second)  ; ;  max  velocity  backwards 

(vel.max.up  <float>  meters/second)  ;;  max  velocity  up 

(fuel .rate  <float>  gallons/second)  ;;  gal  per  sec  at  100X  poser 
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3  Examp  les 

To  get  the  component  number  of  my  hull: 
extern  int32  my _ hull ; 

if  ( (my.hull  ■  cmpnt.locate(vehicle.id,  reader. get .symbol ("hull")))  ■■ 
CHPHT.HOT. FOUID) 

printf ("Vehicle  Xd  doe*  not  aeem  to  have  a  hull\n" ,  vehicle. id) ; 

To  then  give  a  command  to  that  hull: 
if  (my.hull  !»  CMPMT.MOT.FOUin)) 

HULLS.SET.DIRECTIOM.SPEED (vehicle. id,  hull,  dirvec,  speed.  0.0.  0.0); 
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4  Functions 


The  following  sections  describe  each  function  provided  by  librwa,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


4.1  rwaJnit 

void  rva_init() 

rwa. ini t  initializes  librwa.  Call  this  before  any  other  librwa  function. 


4.2  rwa_class Jnit 

void  rwa. class. init (parent.class) 

CLASS.PTR  parent.class ; 

‘parent.class* 

Class  of  the  parent  (declared  with  class.dsclare. class) 

rva.class.init  creates  a  handle  for  attaching  rwa  class  information  to  vehicles.  The  parent.class 
will  likely  be  safobj.dass. 


4.3  rwajdestroy 

void  rva.daaage(vehicle_idt  daaaged) 
int32  vehicle. id; 
int32  daaaged; 

'vehicle. id1 

Specifies  the  vehicle  ID 

'daaaged’  This  sets  (TRUE)  or  <  FALSE)  damage  for  the  rwa  component. 

rva_daaage  This  sets  the  r*a  •  current  ability  to  function  or  not  for  the  specified 

vehicleJd. 
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4.4  rwa^collision 


void  rva.collision(  vehide.id,  position,  coll.type, 
other. id,  other.aais,  other. velocity) 


int32 

vehide.id; 

floated 

position[3] ; 

uint32 

coll.type; 

int32 

other.id; 

floated 

other _aass ; 

floated 

other. velocity [3] ; 

‘vehicle. id’ 

The  vehicle  who  had  the  collision. 

‘position [3]’ 

The  position  of  the  colision; 

‘coll.type’ 

The  type  of  collision 

‘other,  id’ 

The  vehicle  the  collision  was  with  (if  any) 
‘other_nass’ 

The  mass  of  that  other  vehicle  (if  another  vehicle) 
‘other. velocity [3]  ’ 

The  velocity  of  the  other  vehicle  (if  another  vehicle) 


rwa.collision  Handles  the  RWA  running  into  or  being  run  into  by  something. 


4.5  rwa_tick 


void  rva. tick (vehicle. id,  ctdb) 
int32  vehicle. id; 

CTDB  *ctdb; 


‘vehide.id’ 

Specifies  the  vehicle  ID 
‘ctdb’  Specifies  the  terrain  database 


rva.tick  ticks  the  RWA  dynamics. 
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1  Overview 


LibSAFGUI  provides  an  environment  in  which  functionality  can  be  added  to  the  SAF  Graphical 
User  Interface  in  a  simple,  modular  fashion.  It  takes  care  of  laying  out  all  the  major  pieces  (menubar, 
message  log,  editor,  map,  etc.),  and  provides  functions  to  add  new  controls. 


The  library  also  takes  care  of  mode  management.  The  interface  uses  six  different  modes: 

SGUI.SELECT.HOOE 

Selection  mode  ("arrow"  mode).  Note  that  the  software  assumes  only  one  such  mode 
will  be  created. 

SGUI.OBJECT.MODE 

Point,  line,  unit,  etc.  creation  modes. 

SGUI.TASKF RIME. MODE 

Task  frame  creation  mode. 

SGUI.ASSIGH.MODE 

Mission  assignment  mode 

SGUI.TOOL.MODE 

Intends,  coordinate  calculator,  etc.  modes. 

SGUI.MAP.MODE 

Pam,  zoom,  etc.  modes. 


The  system  is  adways  in  one  map  mode,  and  activating  a  new  map  mode  deactivates  the  previous 
one- 


Transitions  between  the  other  modes  are  handled  using  the  following  algorithm: 
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user  presses |  SELECT  OBJECT  TASKFRAME  ASSIGN  TOOL 

I 

current  | 

■ode  I 


SELECT 

- 

PUSH 

PUSH 

PUSH 

PUSH 

OBJECT 

POP 

DISALLOWED 

DISALLOWED 

DISALLOWED 

PUSH 

TASKFRAME 

POP 

PUSH 

DISALLOWED 

DISALLOWED 

PUSH 

ASSIGN 

POP 

PUSH 

PUSH 

DISALLOWED 

PUSH 

TOOL 

POP 

POP/PUSH 

POP/PUSH 

POP/PUSH 

POP/PUSH 

In  this  table,  POP  indicates  that  the  current  mode  is  popped,  and  PUSH  indicates  that  the  pressed- 
on  mode  is  pushed  onto  the  top  of  the  mode  stack.  DISALLOWED  transitions  are  prevented  by  making 
the  corresponding  mode  buttons  in  those  modes  insensitive. 

To  help  the  user  keep  track  of  his  mode  stack,  help  messages  are  pushed  along  with  their 
corresponding  modes.  The  user  is  shown  the  top  three  help  messages. 

A  mode  can  also  specify  additional  help  messages  which  are  shown  when  the  mode  is  current. 

The  X  resources  are  provided  in  the  file  safgui.xrdb  which  is  installed  in  ‘conaon/data’.  Any  of 
these  resources  can  be  overridden  by  making  changes  to  the  user’s  private  .xrssourcss  file  on  the 
X  server  machine. 
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2  Usage 


The  software  library  ‘libsafgui. a’  should  be  built  and  installed  in  the  directory 
‘/comaon/lib/’.  You  will  also  need  the  header  file  ‘libsafgui.h'  which  should  be  installed  in  the 
directory  ‘/comsKm/include/libinc/’.  If  these  files  are  not  installed,  you  need  to  do  a  ‘suite’  in 
the  libsafgui  source  directory.  If  these  files  are  already  built,  you  can  skip  the  section  on  building 
libsafgui. 


2.1  Building  Libsafgui 

The  libsafgui  source  files  are  found  in  the  directory  ‘/common/libsrc/libsafgui’.  ‘RCS’  format 
versions  of  the  files  can  be  found  in  ‘/nfs/common.src/libsrc/libsafgui’. 

If  the  directory  ‘coanoa/libsrc/libaafgui’  does  not  exist  on  your  machine,  you  should  use 
the  ‘genbuild’  command  to  update  the  common  directory  hierarchy. 

To  build  and  install  the  library,  do  the  following: 

•  cd  comaon/liberc/libsafgui 
«  co  RCS/*,v 

•  nuke  install 

This  should  compile  the  library  ‘libsafgul.a’  and  install  it  and  the  header  file  ‘libsafgui.h’ 
in  the  standard  directories.  If  any  errors  occur  during  compilation,  you  may  need  to  adjust  the 
source  code  or  ‘Makefile*  for  the  platform  on  which  you  are  compiling,  libsafgui  should  compile 
without  errors  on  the  following  platforms: 

•  Mips 

e  SGI  Indigo 

•  Sun  Sparc 


2.2  Linking  with  Libsafgui 

Libsafgui  can  be  linked  into  .in  a pplir.it ion  program  with  the  following  link  time  flags:  ‘Id 
[source  .o  files]  -L/common/lib  -lsafgui  -lprivilege  -lXm  -lXt  -Xll’.  If  your  compiler  does 
not  support  ‘-L’  syntax,  you  can  n«*  t  !»••  art  In  v«*  explicitly:  ‘Id  [source  .o  files]  /common/lib/1  ibsafgui  .8 
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Libsafgui  depends  on  libprivilege  and  Motif. 


2.3  Examples 


The  test  program  ‘teat.c’  in  the  libsafgui  source  directory  creates  an  entire  user  interface. 
These  are  a  few  selected  examples: 


To  create  a  quit  button: 


Widget  w; 

extern  SGUT^PTR  my.gui; 
extern  void  quit(); 

w  »  sgui  _idc  ~ubar(my_gui ,  PRI V_SYS0P , 

"File" ,  "Quit" ,  xmPuahButtonWidgetClass) ; 
XtAddCallback(v,  XmNactivateCallback,  quit); 


To  create  the  select  mode: 


SGUI.MODE.PTR  mode; 
extern  SGUI.PTR  my.gui; 
extern  void  mode. callback () ; 

/*  Create  the  mode  */ 

mode  ■  egui.add.mode (my.gui,  SGUI .SELECT. MODE, 

select. bite,  eelect.eidth,  select.height, 

mode. callback,  "Select",  "Select  an  item  to  edit", 

"selecting  an  item  to  edit"); 

/*  Make  this  the  default  mode  */ 
sgui.set.mode (mode) ; 


To  push  a  message  onto  the  message  log: 


extern  SGUI.PTR  my.gui; 

sgui.add.message (my.gui,  "system",  "This  is  a  system  message"); 
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3  Functions 


The  following  sections  describe  each  function  provided  by  libsafgui,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


3.1  sguiJnit 

SGUI.PTR  sgui.init (parent,  title.string) 

Widget  parent; 
char  *title.string; 

‘parent’  Specifies  parent  widget  (needn’t  be  realized) 

‘title.string’ 

Specifies  shell  title  (shown  in  window  manager  decorations) 

sgui.init  initializes  a  SAFSTATION  GUI  top  level  frame.  This  includes  a  menu  bar,  map 
area,  mode  buttons,  etc.  The  returned  handle  is  then  passed  to  other  libsafgui  functions.  The 
parent  widget  needn’t  be  realized  (the  top  level  frame  creates  its  own  shell). 


3.2  sguijset .editor jtoggle 


void  sgui.set. editor. toggle (gui,  toggle) 
SGUI.PTR  gui; 

Widget  toggle; 


‘gui’  Specifies  the  graphical  user  interface 
‘toggle’  Specifies  the  toggle  button  widget 


sgui.set_editor.toggle  gives  the  GUI  a  toggle  button  widget  (not  a  gadget)  which  is  to  be 
kept  in  sync  with  the  state  of  the  editor  (shown/hidden). 


3.3  sgui_shell_widget 

Widget  sgui.shell .widget (gui ) 
SGUI.PTR  gui; 
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‘gui’  Specifies  the  graphical  user  interface 

sgui.shell.widget  returns  the  application  shell  used  by  the  GUI. 


3.4  sgui-realize 

void  s gui. realize (gui ,  big.cursor) 

SGUI.PTR  gui; 
int32  big. cursor; 

’gui’  Specifies  the  graphical  user  interface 

‘big_cursor’ 

Specifies  that  an  oversize  cursor  is  desired 

agui.realize  realizes  the  top  level  frame.  Call  this  after  creating  the  menu  bar,  the  modes, 
etc.  If  the  big_cursor  flag  is  true,  the  library  will  register  a  very  large  (and  easy-to-find)  cursor 
with  X  for  use  on  the  GUI. 


3.5  sgui_map_widget 

Widget  sgui .map. widget (gui) 
SGUI.PTR  gui; 


‘gui’  Specifies  the  graphical  user  interface 

® gui.map. widget  returns  the  map  widget  associated  with  the  passed  GUI.  This  can  be  passed 
to  libsensitive,  libtactmap,  etc. 


3.6  sgui jeditor.widget 

Widget  sgui.edi tor. widget (gui) 
SGUI.PTR  gui; 


‘gui’ 


Specifies  the  graphical  user  interface 
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sgui.editor.vidget  returns  the  editor  widget  associated  with  the  passed  GUI.  This  can  be 
passed  to  libeditor. 


3.7  sgui .map  ^scrollbars 


void  sgui.nap.scrollbars (gui ,  horizontal,  vertical) 
SGUI.PTR  gui; 

Widget  *horizontal ; 

Widget  ♦vertical ; 

‘gui’  Specifies  the  graphical  user  interface 

‘horizontal’ 

Returns  the  horizontal  map  scroll  bar 

‘vertical’ 

Returns  the  vertical  map  scroll  bar 


sgui.aap.scrollbars  returns  the  scroll  bars  attached  to  the  map.  These  default  to  being 
unmanaged,  and  so  must  be  managed  by  the  application  if  they  are  to  be  used.  It  is  up  to  another 
library  (such  as  libPVD)  to  define  callbacks  for  these  scroll  bars. 


3.8  8gui_add_menubar 


Widget  egui_add_nenubar(gui ,  privilege,  nenu.naae, 

button.name ,  vidget.class) 

SGUI.PTR  gui; 

PRIV. LEVEL  privilege; 
char  ♦nenu.name ; 

char  ♦button.nane ; 

WidgetClass  vidget.class ; 


‘gui’  Specifies  the  graphical  user  interface 
‘privilege’ 

Specifies  the  privilege  level  of  the  button 

‘menu_name’ 

Specifies  the  menu  name  (the  button  name  in  the  menu  bar) 
‘button.nane’ 

Specifies  the  name  of  the  button  in  the  pulldown  menu 
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‘widget. class' 

Specifies  the  class  of  the  created  widget  (xmPushButtonWidgetClass,  etc.) 

sgui.add_menubar  adds  a  button  to  the  menubar  structure.  The  menujiame  identifies  the  label 
on  the  menu  bar,  and  the  button_name  specifies  the  label  within  the  pulldown.  A  widget  of  the 
passed  class  is  created  and  returned  so  that  activation  callbacks,  or  other  arguments  can  be  set  by 
the  caller. 


3.9  sguijmanage Jtnenubar 


void  sgui. manage. menubar (gui,  menu.name,  shown) 
SGUI.PTR  gui; 

char  *aenu.name ; 

int32  shown; 


‘gui’  Specifies  the  graphical  user  interface 

‘menu,  name’ 

Specifies  the  menu  name  (the  button  name  in  the  menu  bar) 

‘shown’  Specifies  whether  the  cascade  for  the  menu  should  be  managed 

sgui.nanage.menubar  changes  the  management  of  a  cascade  button  on  the  menu  bar.  If 
shown«TRUE,  the  cascade  will  be  managed;  if  shown*»FALSE,  the  cascade  will  be  unmanaged. 


3.10  sgui.mdd_mode 


SGUI.H0DE.PTR  sgui_add_mode(gui ,  class, 

bitmap.data,  bitmap.width,  bitmap.height , 
callback,  callback.arg, 
help.string,  description) 

SGUI.PTR  gui; 

SGUI.MODE.CLASS  class; 


char  *bitmap.data; 

int32  bitmap.width; 

int32  bitmap.height; 

SGUI.MODE. CALLBACK  callback; 
ADDRESS  callback.arg; 

char  *help. string; 

char  •description; 
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‘gui’  Specifies  the  graphical  user  interface 
‘class’  Specifies  the  class  of  the  mode 
‘bltsap.data’ 

‘bitaap.vidth’ 

‘bltaap.helght’ 

Specify  the  bitmap  which  is  placed  on  the  mode  button 

‘callback’ 

‘callback. arg’ 

Specify  the  function  to  call  when  the  mode  is  entered,  exited,  suspended  or  resumed 
‘help.string’ 

Specifies  the  default  help  string 
‘description’ 

Specifies  a  description  of  the  what  the  user  is  doing  in  that  mode 

sgui.add.awde  adds  a  mode  button  to  the  left  side  of  the  screen.  The  semantics  of  the  mode 
are  dependent  upon  its  class.  The  callback  is  invoked  when  the  mode  is  entered,  exited,  suspended, 
or  resumed.  The  description  should  be  something  like  "editing  a  point"  or  "doing  area  visibility 
calculations". 

The  mode  classes  are  as  follows: 

SGUI.SELECT.MODE 

Selection  mode  ("arrow"  mode).  Note  that  the  software  assumes  only  one  such  mode 
will  be  created. 

SGUI.OBJECT.HODE 

Point,  line,  unit,  etc.  creation  model. 

SGUI.TASKFRAME.NODE 

Task  frame  creation  mode. 

SGUI.ASSIGM.NODE 

Mission  assignment  mode. 

SGUI.TOOL.HODE 

Intends,  coordinate  calculator,  etc.  modes. 

SGUI.HAP.NODE 

Pan,  zoom,  etc.  modes. 

The  callback  should  be  declared  as  follows: 


void  callbackfgui ,  soda,  callback. arg,  state) 
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SGUX.PTR  gui; 

SGUI.MODE.PTR  Bode; 

ADDRESS  callback. arg; 

SGUI. MODE. STATE  state; 

The  gui  and  callback.arg  are  those  passed  to  sgui.add.aode,  and  the  Btoda  is  the  one  returned 
by  that  function.  The  state  is  one  of  the  following: 

SGUI .ACTIVE 

The  mode  is  "current". 

SGUI.SUSPEIDED 

Another  mode  has  been  pushed  on  top  of  this  mode. 

SGUI.RESUMED 

The  mode  has  been  reactivated  after  being  SGUI.SUSPEIDED. 

SGUI.IIACTIVE 

The  mode  has  been  exited. 


3.11  sgui_set_mode 

void  sgui.set.aode(aode) 

SGUI.M0DE.PTR  Bode; 

‘node’  Specifies  the  mode  (implies  a  GUI) 

sgui.SBt.aod*  sets  the  passed  mode  (created  with  sgui.add.aods)  to  active.  This  should  be 
used  at  initialization  to  set  the  default  modes  of  the  system.  Once  the  system  is  running,  this  can 
be  called  to  simulate  user  behavior;  however,  since  some  modes  are  not.  always  available,  this  may 
not  always  succeed  at  run  time. 


3.12  sgui .leave .mode 

void  sgui.l*av*.aod*(gui) 

SGUI.PTR  gui; 

‘gui’  Specifies  the  graphical  user  interface 
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sgui.leave.node  exits  the  current  mode.  This  should  be  called  by  editor  Done  and  Abort 
buttons.  It  is  equivialent  to  calling  sgui.set.aode  with  a  mode  of  the  SELECT  class. 


3.13  sgui-mode-control 

void  sgui.aode.control (mode .  disable) 

SGUI.HODE.PTR  node; 
uint32  disable; 

‘■ode’  Specifies  the  mode 

‘disable’  Specifies  whether  that  mode  should  be  disabled  (regardless  of  the  current  mode  or  its 
semantics) 

sgui.aode.control  sets  control  flags  for  the  passed  mode.  Currently  this  is  just  a  disable 
flag,  which  causes  the  mode  to  be  insensitive  when  set. 


3.14  sgui-push -help 

void  sgui. push. help (node ,  help.string) 
SGUI.HODE.PTR  aode; 
char  * help.string; 

‘■ode’  Specifies  the  current  mode 
‘help.string’ 

Specifies  the  string  to  push 


sgui.push.hslp  pushes  an  additional  help  message  for  the  passed  mode. 


3.15  sgui^pop Jhelp 


void  sgui.pop.hslpCaode ,  pop. all) 
SGUI.HODE.PTR  aode; 
int32  pop. » 11 ; 


‘node’  Specifies  the  current  mode 
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‘pop. all’  Specifies  whether  to  pop  all,  or  just  topmost 


sgui._pop.help  pops  the  additional  mode  help  message  (if  any)  for  the  passed  mode.  If  pop. all 
is  TRUE,  all  pushed  messages  will  be  popped;  otherwise,  only  the  topmost  will  be. 


3.16  sgui-set -urgent -help 


▼old  sgui.set. urgent. help (aods,  help.string) 
SGUI.HODE.PTR  aode; 
char  * help. string; 


‘node’  Specifies  the  current  mode 
‘help.string’ 

Specifies  the  string  to  show  or  NULL 


sgui.set.urgent.help  pushes  an  additional  help  message  for  the  passed  mode.  The  message 
is  displayed  above  other  help  messages  in  a  distracting  manner.  Pass  NULL  to  remove  the  urgent 
message. 


3.17  sgui .message Jog 

void  sgui_aessage.log(gui ,  shown) 
SGUI.PTR  gui; 
int32  shown; 

‘gui’  Specifies  the  graphical  user  interface 
‘shown’  Specifies  whether  to  show  the  message  log 


sgui.asssags.log  changes  the  status  of  the  message  log  (shown=TRUE,  hidden=FALSE). 


3.18  sgui^editor 


void  sgui.sditorCgui,  shown) 
SGUI.PTR  gui; 
int32  shown; 
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‘gui’  Specifies  the  graphical  user  interface 

‘shown’  Specifies  whether  to  show  the  editor 


s  gui  .editor  changes  the  status  of  the  editor  (shown=TRUE,  hidden=FALSE). 


3.10  sgui_add_message 


void  sgui_add.message(gui,  kind,  message) 
SGUI.PTR  gui; 
char  *kind; 
char  ^message ; 


‘gui’  Specifies  the  graphical  user  interface 
‘kind’  Specifies  the  kind  of  message 
‘message’  Specifies  the  message  to  log 


sgui.add_message  adds  a  message  to  the  message  log.  The  kind  is  used  to  name  the  output 
widget,  so  that  resources  (fonts,  colors,  etc.)  can  be  used  to  customize  output  styles;  it  must  be 
statically  declared  (such  as  a  quoted  string  constant,  or  a  libreader  symbol). 


3.20  sgui_clear .message Jog 

void  s gui. clear.message.log (gui) 

SGUI.PTR  gui; 

‘gui’  Specifies  the  graphical  user  interface 
sgui_claarjnaasags.log  empties  the  message  log. 


3.21  sgui^error 


void  sgui. error (gui,  format,  args...) 
SGUI.PTR  gui; 
char  format  [] ; 
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‘gui’  Specifies  the  graphical  user  interface 

‘format’  Specifies  the  format  of  the  error  (like  fprintf) 

‘args’  Speicifies  arguments  to  format 

sgui.error  reports  an  error  on  the  GUI,  in  a  manner  similar  to  fprintf.  The  error  is  reported  in 
three  places  simultaneously:  stderr,  the  message  log  (kind  ==  "system11),  and  in  a  popup.  This 
should  be  only  be  called  for  errors  which  might  be  meaningful  to  a  user. 


3.22  sgui-safe -focus 

void  sgui.safe.focus(gui) 

SGUI.PTR  gui; 

‘gui’  Specifies  the  graphical  user  interface 

sgui.safe.focus  moves  Motifs  input  focus  to  a  "safe"  place  (the  button  for  select  mode).  This 
can  be  used  when  an  editor  is  exited  to  guarantee  that  focus  does  not  remain  with  the  inactive 
editor. 
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1  O  verview 


Libsafobj  provides  the  class  superstructure  in  which  all  vehicle  subclasses  reside.  There  are  two 
kinds  of  SAF  objects,  locals  and  remote.  The  subclasses  which  make  up  locals,  and  the  default 
configurations  of  these  subclasses  for  each  type  of  vehicle  are  stored  in  a  configuration  file.  Remotes 
are  always  made  up  of  a  fixed  set  of  subclasses  (entity,  pbtab,  and  others). 


Examples  of  ModSAF  local  vehicles  include:  airplanes,  tanks,  and  missiles.  Since  the  simulation 
requirements  are  less  demanding  for  a  missile,  its  class  superstructure  does  not  need  to  be  as 
extensive  as  that  needed  for  an  airplane  or  tank. 


Assume  that  the  configuration  file  that  defines  the  model  parameters  for  a  missile  had  the 
following  contents: 


US.SPARROW.MODEL.PARAMETERS  { 

( SN.TaskManager ) 

(SM.Entl.ty  (length. threshold  10.0) 

(vidth. threshold  10.0) 

(height. threshold  10.0) 

(rotation. threshold  3.0) 

(turret. threshold  3.0) 

(gun. threshold  3.0) 

(vehicle. class  vehideClassSimple) 

(guises  snmition_US.Sparrov  munition. US.Sparrov) ) 
(SM.Collision  (check  buildings  platforms) 

(announce  buildings) 

(duration  5000) 

(feature.aass  10000.0) 

(fidelity  high)) 

(SM.Detonation  (check  platforms) 

(announce  buildings) 

(detonation.radius  20.0) 

(fidelity  low)) 

(SM.Components  (hull  SM.MissileHull) ) 

(SM_MissileHull  (sensor.name  apg-71) 

( sensor. on_board  false) 

(pursuit.mode  lead.pursuit) 

(range  22880.0) 

(launch.speed  500.0) 

(safe. time  1.0) 

(loal.time  2.0) 

(aiax.bum_time  60.0) 

(burn.max.turn  5.0) 

(coast. max. turn  5.0) 

(directionality  12.566370614359)) 
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> 

The  class  superstructure  to  correspond  to  the  object  defined  above  is  shown  below. 


Class  Superstructure  When  SAF  Object  (SAFobj)  is  Local  Missile  Vehicle 


♦ - ♦ 

I  SAFobj  | 

I  Class  I 

♦ - ♦ 

I 

I 


1 

1 

1 

1 

collision 

1 

1 

1 

subclass 
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1 

1 

I 

♦ — — - + 

I t&skm&nager I 
I subclass  | 

+ - ♦ 

♦— - — ♦ 

I  entity  I 
I  subclass  I 
+ - ♦ 


♦ - - ♦ 

I  detonation  I 
I  subclass  I 


I 


I  components 
I  subclass 
♦ - - - 


♦ - ♦ 

I  hulls  I 
I  subclass  | 
♦ - 


♦ 

I 

I 

+ 


The  sample  configuration  file  indicates  the  modeling  parameters  and  and  subclasses  (libraries) 
necessary  for  handling  the  simulation  requirements  for  a  Sparrow  missile.  The  libentity,  libcollision, 
libdetonation,  and  libtaskmgr  libraries  take  care  of  making  a  simulated  Sparrow  missile  a  simulated 
network  entity  that  can  strike  (collide  with)  a  target,  detonate,  and  perform  tasks.  In  addition,  a 
simulated  Sparrow  missile  will  have  one  simulated  component  (a  hull). 

The  class  superstructure  for  an  airplane  or  tank  includes  many  of  the  subclasses  (such  as  task 
manager,  collision,  components)  required  for  a  missile.  However,  many  more  subclasses  are  required 
to  meet  the  simulation  requirements  of  an  airplane  or  tank.  Some  of  these  additional  simulation 
requirements  include  the  following  actions: 

•  calculate  how  it  is  damaged  when  hit  by  direct  fire; 

•  keep  track  of  the  current  level  of  its  fuel  and  ammunition; 

•  have  it  "appear  in"  the  position- based  table  (pbtab); 

•  have  it  "appear  in"  the  vehicle  table  (vtab); 

•  and  spot  other  vehicles. 


Adding  a  subclass  requires  making  the  following  changes  to  this  library: 
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1.  Modify  safobj.init  to  initialize  the  subclass. 

2.  Modify  aaf obj _create_local_ with. id  to  create  the  subclass  at  the  appropriate  point  (after 
those  subclasses  in  lower  layers,  and  before  those  in  higher  layers). 

3.  Modify  safobj.destroy.local  to  also  destroy  the  new  subclass. 

4.  Modify  aafobj.install.handlera  (a  private  function)  to  install  handlers  for  all  new  events 
which  the  subclass  needs  (such  as  the  receipt  of  a  particular  kind  of  packet). 

5.  Extend  existing  handlers  or  write  new  handlers  for  all  events  which  the  subclass  needs,  putting 
the  invocation  of  the  event  at  an  appropriate  point  relative  to  other  subclass  handlers. 
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2  Algorithms 


Libsafobj  can  create  or  update  a  SAF  object  (safobj).  A  safobj  is  considered  local  when  it 
originates  from  this  computer  and  remote  when  it  originates  elsewhere  on  the  LAN. 


2.1  Local  Safobj  Creation 

The  function  safobj  .create.local  is  used  when  making  a  local  safobj  such  as  a  plane  or  tank 

vehicle.  Input  passed  to  this  function  serves  as  a  configuration  file  key  to  find  default  values  for  all 

subclasses.  An  input  unit  entry  identifies  the  unit  that  caused  the  creation  of  this  object,  it  may 

be  NULL.  The  steps  performed  by  this  function  to  create  a  local  safobj  are  as  follows: 

1.  Calls  vtab.vehicla.number  in  libvtab  to  generate  a  vehicle  table  (vtab)  id  from  the  entity’s 
network  id. 

2.  Makes  the  local  safobj  by  creating  a  block  of  user  data  to  hold  the  pointers  to  the  subclass 
information  and  then  stores  that  pointer  as  the  uaer.data  of  the  libvtab  vehicle. 

3.  Composes  the  safobj  subclasses  by  calling  a  create  function  for  all  the  subclasses  that  make  up 
a  local  vehicle  (all  subclasses  that  are  listed  in  the  object's  configuration  file).  For  example, 
a  call  to  pbt.craata  in  libpbtab  is  made  when  the  configuration  file  has  a  SM_PBTab  entry. 
This  call  will  result  in  the  creation  of  the  position-based  table  (pbt)  class  information  and  the 
attachment  of  that  information  to  the  vehicle’s  block  of  libclass  user  data.  More  information 
about  a  safobj  subclass  can  be  found  in  the  ModSAF  library  documentation  and  in  the  ModS  AF 
Program  miner’s  Guide  (see  section  ‘ModSAF  Software  Architecture’  in  ModSAF  Programmer’s 
Guide). 

4.  Calls  prev.creata  in  libpreview  to  create  the  preview  class  information  and  attach  it  to  the 
vehicle’s  block  of  libclass  user  data.  Libpreview  handles  the  ModSAF  Previewer,  an  optional 
part  of  the  user  interface  which  can  provide  a  rudimentary  3D  out-the-window  view  of  terrain 
and  3D  dynamic  models  for  network  entities. 

5.  Calls  pvd. create  in  libpvd  to  create  the  plan  view  display  (pvd)  class  information  and  attach 
it  to  the  vehicle’s  block  of  libclass  user  data.  Libpvd  handles  the  ModSAF  PVD,  the  tactical 
map  shown  on  the  user  interface.  The  PVD  reflects  the  updated  positions  of  network  entities. 

6.  Posts  the  periodic  invocation  of  local.tick  with  libsched  to  schedule  subclass  ticking  accord¬ 
ing  to  the  tick_rate  value. 

7 .  Fires  the  event  named  safobj  .local. added.event  to  say  that  there  is  one  more  locally  created 
vehicle  now.  Applications  that  have  attached  a  handler  to  this  event,  will  have  their  registered 
callback  functions  invoked. 

S.  If  this  is  a  unit  entry,  then  call  pm.monitor.unit  to  monitor  changes  made  to  the  unit. 
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9.  Returns  the  vehicle  ID  of  the  new  vehicle  (or  0,  meaning  creation  failed). 


2.2  Local  Safobj  Updating 

When  a  safobj  is  ticked,  the  function  local. tick  does  the  following: 

1.  Checks  to  make  sure  the  input  vehicle  id  is  present  in  the  vehicle  table.  Exits  if  that  id  is  not 
found  in  the  vehicle  table. 

2.  Performs  vehicle  tick  processing  in  the  following  order:  input  PDU’s,  dynamics,  output  PDU’s, 
sensors,  tasks,  and  user  interface.  PDU  input  processing  is  performed  first  since  am  input  event 
such  as  a  collision  or  impact  could  disable  a  vehicle  component.  Dynamics  processing,  which 
includes  hull  and  turret  movement  and  weapon  firing,  is  performed  by  ticking  the  collection 
of  hull,  turret,  and  gun  components  that  a  particular  vehicle  has  available.  Collision  and 
detonation  detections  are  also  part  of  dynamics  processing.  Once  dynamics  processing  has 
finished,  enough  processing  has  occurred  to  warrant  PDU  output  processing  which  includes  the 
sending  of  vehicle  appearance  and  designator  packets.  Sensor  processing,  which  only  occurs  if 
the  vehicle  is  still  alive,  handles  the  visual  and  radar  sensory  input  processing.  Task  processing 
follows  since  tasks  often  require  a  list  of  detected  vehicles  generated  from  the  sensor  processing. 
The  last  step  of  a  vehicle  tick  is  the  updating  of  the  ModSAF  user  interface. 


2.3  Remote  Safobj  Creation 

A  remote  safobj  can  be  created  or  updated  when  a  vehicle  appearance,  designate,  or  stealth 
packet  is  received.  When  a  remote  entity  is  first  received,  an  entry  is  made  in  the  vehicle  table  with 
the  appropriate  type  since  the  the  per- vehicle  subclass  information  and  the  processing  requirements 
for  a  safobj  differ  according  to  its  type. 

The  function  saf obj .create. renot e,  used  when  making  a  remotely  created  safobj,  does  the 
following: 

1.  Makes  the  remote  safobj  by  creating  a  block  of  user  data  to  hold  the  pointers  to  the  subclass 
information  and  then  stores  that  pointer  as  the  user.data  of  the  libvtab  vehicle. 

2.  Composes  the  safobj  subclasses  by  calling  a  create  function  for  all  the  subclasses  that  make 
up  the  remote.  The  subclasses  needed  by  a  remote  differ  according  to  its  type.  When 
the  type  is  a  VTAB.REMOTE. VEHICLE,  VTAB.REMOTE. MISSILE,  VTAB. REMOTE. STRUCTURE,  or 
VTAB.REMOTE.DESIGNATOR,  pbt.create  in  libpbtab  is  called.  When  the  type  is  a 
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VTAB. REMO TE_ DES I G M ATO R,  dsg_ create  in  libdesignate  is  called.  When  the  type  is 
VTAB_REMOTE_STEALTH,  steal th_create  in  libstealth  is  called.  When  the  type  is  a 
VTAB.REMOTE. VEHICLE,  VTAB.REMOTE.MISSILE,  or  VTAB_ REMOTE. STRUCTURE,  ent.create  in 
libentity  is  called.  These  functions  build  the  subclass  information  and  attach  it  to  the  vehicle’s 
block  of  libclass  user  data. 

3.  Calls  prev.create  in  libpreview  to  create  the  preview  class  information  and  attach  it  to  the 
vehicle’s  block  of  libclass  user  data.  Libpreview  handles  the  ModSAF  preview,  an  optional 
part  of  the  user  interface  which  provides  a  rudimentary  3D  out-the- window  view  of  terrain  and 
3D  dynamic  models  for  network  entities. 

4.  Calls  pvd. create  in  libpvd  to  create  the  plan  view  display  (pvd)  information  and  attach  it  to 
the  vehicle’s  block  of  libclass  user  data.  Libpvd  handles  the  ModSAF  PVD,  the  tactical  map 
shown  on  the  user  interface.  The  PVD  reflects  the  updated  positions  of  network  entities. 

5.  Posts  the  periodic  invocation  of  renote.tick  with  libsched  to  schedule  subclass  ticking  ac¬ 
cording  to  the  reaote.tick.rata  value. 


2.4  Remote  Safobj  Updating 

When  a  remote  safobj  is  ticked,  the  function  reaote.tick  does  the  following: 

1.  Exits  if  the  input  vehicle  id  is  not  present  in  the  vehicle  table  (vtab). 

2.  Invokes  entity  tick  processing  via  a  call  to  ent.tick  in  libentity.  Exits  if  ent.tick  times  out 
the  remote  causing  the  vehicle  to  no  longer  be  present  in  the  vehicle  table. 

3.  Invokes  the  designator  tick  processing  via  a  call  to  dsg_tick  in  libdesignator.  Exits  if  dsg_tick 
times  out  the  remote  causing  the  vehicle  to  no  longer  be  present  in  the  vehicle  table. 

4.  Invokes  the  stealth  tick  processing  via  a  call  to  steal th_tick.  Exits  if  stealth_tick  times 
out  the  remote  causing  the  vehicle  to  no  longer  be  present  in  the  vehicle  table. 

5.  Updates  the  user  interface  by  a  call  to  pvd.tick  in  libpvd. 
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3  Global  Variables 


The  sections  below  describe  the  global  variables  by  including  a  synopsis  and  a  description. 


3.1  safob  j  Jocal_added_event 


extern  CALLBACK.EVEMT.PTR  safobj  _local_added_event ; 


safobj .local. added.event  is  a  libcallback  event  which  cam  be  accessed  after  libsafobj  is  ini¬ 
tialized.  Applications  may  attach  a  safobj .local.added. event. handler  to  this  event  via  (see 
section  ‘callbackjegister  .handler’  in  LibCallback  Programmer’s  Manual). 


void  safobj .local.added. event_handler( vehicle. id,  user.data) 
int32  vehicle,  id; 

ADDRESS  user.data; 


safobj  . local. added.event.handler  is  called  when  a  new  local  entity  is  simulated, 
vehicle.id  will  contain  the  id  of  the  new  vehicle  being  simulated. 


3.2  safob  j  Jocal_deleted  .event 


extern  CALLBACK.EVERT.PTR  safobj .local.deleted.event ; 


safobj  .local.deleted.event  is  a  libcallback  event  which  can  be  accessed  after  libsafobj  is 
initialized.  Applications  may  attach  a  safobj  .local.deleted.event  .handler  to  this  event  via 
(see  section  ‘callbacluregisterJiandler’  in  LibCallback  Programmer’s  Manual). 


void  safobj .local.deleted.event .handler (vehicle. id,  user.data) 
int32  vehicle.id; 

ADDRESS  user.data; 


safobj .local.deleted.event.handler  is  called  when  a  local  entity  is  about  to  be  destroyed, 
vehicle.id  will  contain  the  id  of  the  vehicle  which  is  about  to  be  destroyed. 
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4  Functions 

The  following  sections  describe  each  function  provided  by  libsafobj,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


4.1  safobj_init 

void  safobj_init(ctdb,  db,  quad .data,  ent. valve) 

CTDB  *ctdb; 

P0_ DATABASE  *db; 

QUAD. DATA  * quad .data; 

PV_ VALVE. PTR  ent. valve; 

‘ctdb’  Specifies  the  terrain  used  in  this  exercise 
‘db’  Specifies  the  persistent  object  database  used  in  this  exercise 

‘ent.  valve’ 

Specifies  the  packet  valve  used  in  this  exercise  for  creating  local  vehicles 

eafobj.init  initializes  libsafobj.  Call  this  before  any  other  libsafobj  function.  Note  that  this 
function  will  call  the  .dasa.init  routines  for  all  vehicle  subclasses.  Hence,  you  should  call  their 
primary  init  routines  before  safobl.init. 


4.2  safob j .create .remote 

void  safobj_create_remote( vehicle. id,  simnet.id,  vtab.type,  tick.rate) 
int32  vehicle. id; 

VehidelD  *simnet_id; 
uint 16  vtab.type ; 

int32  tick_rate; 

‘vehicle. id’ 

Specifies  the  libvtab  ID  assigned  to  the  vehicle. 

‘simnet.id’ 

Specifies  the  vehicle’s  network  VehiclelD. 

‘vtab.type’ 


Specifies  the  vtab  type  of  the  vehicle. 


12 


LibSAFObj  Programmer’s  Guide 


‘tick.rate’ 

Specifies  the  rate  at  which  the  vehicle  should  tick. 

eaf obj .create.reaote  creates  a  remote  vehicle  with  the  passed  parameter  values.  Automati¬ 
cally  creates  pbtab  and  entity  subclasses,  and  posts  ent.tick  function  on  scheduler. 

See  section  ‘remoteJnit’  in  LibRemote  Programmer’s  Guide. 


4.3  safobj^create Jocal 


int32  safobj_create_local(name_synbol,  vtab.type,  tick.rate,  unit. entry) 
char  *naae.synbol ; 

uintld  vtab.type; 

int32  tick.rate ; 

PO.DB.EMTRY  *unit_entry; 

‘name.synbol’ 

Specifies  the  symbolic  name  of  the  type  of  vehicle  to  create. 

‘vtab.type’ 

Specifies  the  vtab  type  of  the  vehicle. 

‘tick.rate’ 

Specifies  the  rate  at  which  the  vehicle  should  tick. 

‘unit,  entry’ 

Itendifies  the  unit  which  caused  the  creation  of  this  object.  It  may  be  null. 


aafobj.create.local  creates  a  local  vehicle.  The  naBe.synbol  is  used  as  the  configuration 
file  key  to  find  default  values  for  all  subclasses.  The  vehicle  ID  of  the  new  vehicle  is  returned  (or 
0,  meaning  creation  failed). 


4.4  safob j_create Jocal.with Jd 


int32  safobj.create.local.vith.idCnaoe.syinbol,  vtab.type,  tick.rate. 


char  enaae.aymbol; 

uintlfi  vtab.type ; 

int32  tick.rate; 

VehidelD  *aianet_id; 
PO.DB.EHTRY  * unit .entry; 


sismet.id,  unit.entry) 
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‘name.syabol’ 

Specifies  the  symbolic  name  of  the  type  of  vehicle  to  create. 

‘vtab.type’ 

Specifies  the  vtab  type  of  the  vehicle. 

‘tick_rate’ 

Specifies  the  rate  at  which  the  vehicle  should  tick. 

‘simnet.id’ 

Specifies  the  network  id  to  be  used  for  this  vehicle.  This  is  useful  when  creating  a 
vehicle  that  used  to  be  simulated  by  a  remote  simulator  (this  process  is  referred  to  as 
migration),  or  to  create  a  vehicle  on  behalf  of  another  simulator. 

‘unit.entry’ 

Itendifies  the  unit  which  caused  the  creation  of  this  object.  It  may  be  null. 

a af obj. create. local. vith.  id  creates  a  local  vehicle.  The  name.eymbol  is  used  as  the  con¬ 
figuration  file  key  to  find  default  values  for  all  subclasses.  The  vehicle  ID  of  the  new  vehicle  is 
returned  (or  0,  meaning  creation  failed ). 


4.5  safobj.jdestroyJoca] 

void  safobj_deatroy_local(vehicle.id,  is.migration) 
int32  vehicle. id; 
int32  ia.nigration; 

‘vehide.id’ 

Specifies  the  vehicle  to  destroy. 

‘is.migration’ 

Specifies  whether  the  vehicle  is  really  being  destroyed  (FALSE),  or  just  migrating  to 
another  host  (TRUE). 

aafobj.destroy.local  destroys  a  local  vehicle  and  frees  all  the  memory  associated  with  that 
vehicle  (including  all  subclasses). 


4.6  safob jjdestroy .remote 

void  aalobj .destroy. rea>o t a  ( vehi c  1  e. id) 
int32  vehicle. id; 
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‘vehicle.id’ 

Specifies  the  vehicle  to  destroy. 

saf obj .destroy.reaote  destroys  a  remote  vehicle  and  frees  all  the  memory  associated  with 
that  vehicle  (including  all  subclasses).  Remotes  are  usually  automatically  destroyed  when  timed 
out  by  libpktvalve.  Some  applications  may  use  this  function  during  vehicle  migration  to  destroy 
the  remote  version  of  an  entity  before  simulating  it  as  a  local  vehicle. 


4.7  safob j jcreate-preview 

,  int32  safobj_create_previev(previeHer ,  previev.nuaber,  tick.rate) 

PREV.PTR  previever; 
int32  previev.nuaber; 
uint32  tick.rate; 

‘prevlever’ 

Specifies  the  previewer  to  insert  into  the  vehicle  table 
‘previev.nuaber’ 

Specifies  the  number  of  the  previewer  (in  case  there  are  more  than  one  previews). 

‘tick_rate’ 

Specifies  the  rate  at  which  the  previewer  should  tick. 

■afobj.create.previev  creates  an  entry  in  the  vehicle  table  for  a  LOCAL.STEALTH  view.  This 
allows  the  GUI  to  show  the  position  of  each  preview  on  the  map. 


4.8  safob j_mobility Jkill 

void  vaf obj .nobility.killC vehicle. id) 
int32  vehicle. id; 

‘vehicle. id’ 

Specifies  the  local  vehicle  to  mobility  kill. 

safobj.mobility.kill  performs  the  processing  neccesary  to  mobility  kill  a  local  vehicle. 
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4.0  safobj -fire -kill 

void  safobj .fire.kill( vehicle. id) 
int32  vehicle.id; 

‘vehicle-id’ 

Specifies  the  local  vehicle  to  firepower  kill. 

safobj.fire.kill  performs  the  processing  neccesary  to  firepower  kill  a  local  vehicle. 


4.10  safob j-catastrophic -kill 

void  safobj -cataatrophic-kill (vehicle-id) 
int32  vehicle. id; 

‘vehicle. id’ 

Specifies  the  local  vehicle  to  catastrophic  kill. 

safobj  .catastrophic-kill  performs  the  processing  neccesary  to  catastrophic  kill  a  local  ve¬ 
hicle. 
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1  O  verview 

TEMPLATE:  Describe  what  this  library  does  here. 

1.1  Examples 

TEMPLATE:  Give  examples  here. 
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2  Functions 


The  following  sections  describe  each  function  provided  by  libsafsam,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 

TEMPLATE:  Adjust  alignment  of  descriptions 

TEMPLATE:  Correct  argument  lists  and  descriptions  of  these  functions. 


2.1  safsamjnit 

void  safflan_init(po_db,  tcc) 

PO.DATABASE  *po_db; 

COORD.TCC.PTR  tcc; 

‘po.db’  Specifies  the  PO  database 

‘tcc’  Specifies  the  TCC 

safsaa.init  initializes  libsafsam.  Call  this  before  any  other  libsafsam  function. 


2.2  safsamjnit 

void  safsaa.global_tick() 

safsaiB.global.tick  ticks  all  the  samuel  methodology  vehicles. 


2.3  safsam.class Jnit 

void  safsajn_class_init(parent_class) 

CLASS.PTR  parent. cl as 8 ; 

‘parent. class’ 

Class  of  the  parent  (declared  with  class. declare. class) 
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•afaea.clmae.iait  creates  a  handle  for  attaching  sa&am  class  information  to  vehicles.  The 
parant.daaa  will  likely  be  aafobj.claaa. 


2.4  safsam .create 

void  safaaa_cr#ate( vehicle. id,  parana ,  unit.entry) 
int  vehicle. id; 

SAFSAH.PARAKETRIC.DATA  *params; 

PO.DB.EITRY  * unit. entry; 

‘vehicle.id’ 

Specifies  the  vehicle  ID 

‘paraaa’  Specifies  initial  parameter  values 
‘unit.entry’ 

Specifies  the  unit  being  created 

saf  saa.create  creates  the  sa&am  class  information  for  a  vehicle  and  attaches  it  vehicle’s  block 
of  libclass  user  data. 


2.5  safsam  .destroy 

void  safsaa.destroy(vehicle.id) 
int  vehicle.id; 

‘vehicle.id’ 

Specifies  the  vehicle  ID 

aafsaa.deatroy  frees  the  sa&am  class  information  for  a  vehicle.  This  should  be  called  before 
freeing  the  class  user  data  with  claas.free.user.data. 
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1  Overview 

TEMPLATE:  Describe  what  this  library  does  here. 
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2  Examp  les 


TEMPLATE:  Give  examples  here. 


Libsafeoar  Programmer’s  Guide 


Chapter  3:  Functions 


5 


3  Fun  ctio  n  s 

The  following  sections  describe  each  function  provided  by  libsafsoar,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 

TEMPLATE:  Adjust  alignment  of  descriptions 

TEMPLATE:  Correct  argument  lists  and  descriptions  of  these  functions. 

3.1  safsoarJnit 

▼old  saf soar.init(db) 

PO.DATABASE  *db; 

‘db’  Specifies  PO  database 

safsoar.init  initializes  libsafsoar.  Call  this  before  any  other  libsafsoar  function. 

3.2  safsoar_class Jnit 

void  saf soar. class. init (parent. class) 

CLASS.PTR  parent.clans; 

‘parent.clans’ 

Class  of  the  parent  (declared  with  class.declare.clsuBs) 

saf  soar.class.init  creates  a  handle  for  attaching  safsoar  class  information  to  vehicles.  The 
parent.clans  will  likely  be  saf obj .class. 


3.3  safsoar-jcreate 


void  safsoar.create (vehicle. id,  paxams,  unit.entry) 
int  vehicle.id; 

SAFSOAR_PARAMETRIC.DAT A  *paraas; 

PO.DB.EMTRY  * unit. entry; 
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‘vehicle.id’ 

Specifies  the  vehicle  ID 
‘par ana’  Specifies  initial  parameter  values 

‘unit,  entry’ 

Specifies  unit  entry 

aafaoar.create  creates  the  safsoar  class  information  for  a  vehicle  and  attaches  it  vehicle’s  block 
of  libclass  user  data. 


3.4  safaoar^deatroy 

void  safaoar.deatroyC vehicle. id) 
int  vehicle. id; 

‘vehicle. id’ 

Specifies  the  vehicle  ID 

aefaoar.deatroy  frees  the  safsoar  class  information  for  a  vehicle.  This  should  be  called  before 
freeing  the  class  user  data  with  claaa.free.uaer.data. 
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1  Overview 


Libsched  is  a  non-preemptive,  ring  based  scheduler  which  calls  functions  either  periodically,  or 
once  after  a  specified  delay.  The  application  program  defines  the  number  of  rings,  and  the  period 
of  each.  Libsched  will  then  invoke  all  scheduled  functions  in  sequence,  invoking  a  given  function  at 
a  rate  no  faster  than  that  specified  for  its  ring. 

Rings  are  not  prioritized.  Hence,  as  the  system  load  increases,  functions  in  faster  rings  may  be 
called  with  the  same  frequency  as  functions  in  slower  rings. 

The  scheduler  is  self  monitoring,  so  that  if  system  performance  drops  below  an  acceptable 
minimum,  the  application  will  be  notified. 

Although  the  ModSAF  system  uses  the  scheduler  to  run  the  entire  system,  it  can  be  used  in  a 
slave  mode  as  well.  For  example,  a  tank  simulator  could  perform  all  synchronous  tick  processing, 
then  start  the  scheduler  with  a  deadline  of  just  prior  to  the  next  frame.  The  scheduler  will  invoke 
periodic  and  deferred  functions  until  that  time  is  passed,  at  which  point  control  returns  to  the 
simulator  main  loop. 

There  are  also  calls  to  have  the  scheduler  invoke  all  functions  that  are  pending  and  then  return. 

The  scheduler  bases  its  timing  on  libtime's  time.realtime. clock.  Periodic  and  deferred  func¬ 
tion  calls  are  relative  to  this  real  time  clock.  Libsched  also  provides  a  facility  to  specify  that  a 
function  be  called  at  a  specific  time  on  the  simulation  clock  (see  Section  3.7  [sched'simtime'fnd], 
page  7). 
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2  Examp  les 

The  extensive  test  program  ‘test,  c’  in  the  libsched  source  directory  shows  example  usage  of  all 
libsched  functions.  Here  are  some  highlights: 

To  call  a  function  thingy_tick(5,  3.4,  "foo")  once  every  67  milliseconds: 


tick  •  sched_periodic_fncl(thingy_tick,  SCHED.ASAP,  67,  0, 

A.INT,  5, 

A. DOUBLE,  3.4, 

A.PTR,  "foo", 

A. END) ; 


To  call  a  function  stop_doing_that()  after  a  5132  millisecond  delay: 


stop  *  8ched_deferred_fncKstop.doing.that,  5132,  0,  A.END) ; 


To  cancel  the  call  to  stop_doing_that()  before  it  occurs: 


sched_cancel_fncl(stop) ; 


To  call  a  function  do_that.nov()  in  2000  simulated  milliseconds: 


sched_sintime_fncl(do_that_nov,  time_last_sisrulation_clock+2000,  0, 

A.END) ; 
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3  Fun  ctio  n  s 


The  following  sections  describe  each  function  provided  by  libsched,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


3.1  schedjnit 


void  ached. init (nr inga,  period [0],  . ...  period [nrings-1]) 
int32  nr inga; 

uint32  period [0] . period [nringa- 1] ; 


‘nr inga’  Specifies  number  of  event  rings  periods. 

‘period [0] ,  ....  period [nringa-1]’ 

Specify  durations  of  each  period  in  increasing  order  (in  milliseconds). 


ached,  init  initializes  the  scheduler.  It  specifies  how  many  periodic  event  rings  will  be  used 
and  their  periods.  The  private  constant  HAX.RIMGS  in  ‘1 ibsched. local .h’  sets  the  upper  limit  (it 
can  be  increased  to  be  arbitrary  large  if  need  be).  The  current  value  of  this  constant  is  8. 


3.2  ached  .invoke  jfunction8_until 

void  sched.invoke.f unctiona.until (deadline) 
uint32  deadline; 


‘deadline’ 

Specifies  when  to  stop  invoking  functions. 

sched.invoke.f  unctions  .until  rum)  the  scheduler  until  the  specified  deadline.  The  time  used 
is  that  from  tjuse.realtine.clock  (see  section  ‘timejrealtimejdock’  in  LibTime  Programmer’s 
Manual).  A  deadline  of  OxFFFFFFFF  will  run  indefinitely. 


3.3  ached Jnvoke_functions_once 


void  sched.invoke.f unctions.onceQ 
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ached. invoke. functions .ones  forces  the  scheduler  to  invoke  all  pending  functions  then  return. 

That  is,  all  functions  that  have  been  scheduled  to  be  invoked  at  or  before  the  time  ached. invoka.f unctions, 
is  called  will  be  invoked.  The  time  used  is  that  from  tiae.realtiae.dock  or  tiae.8iBulation.tiBe. 

No  calls  are  made  to  tiae_advance_8iaulation.clock  so  simulated  time  is  not  advanced,  (see 
section  ‘time_realtimejclock’  in  LibTime  Programmer’s  Manual). 


3.4  sched  Jin  voke  .realtime  _fu  notions  .once 
void  sched.invoke_realtiae_functions_onceO 

ached.invoke.realtiae.functiona.once  forces  the  scheduler  to  invoke  all  pending  realtime 
functions  then  return.  That  is,  all  functions  that  have  been  scheduled  to  be  invoked  at  or  before  the 
realtime  ached.invoke.realtiae.functiona.once  is  called  will  be  invoked.  The  time  used  is  that 
from  tiae.realtiae.dock.  No  calls  are  made  to  tiae_advance.8iBulation.dock  so  simulated 
time  is  not  advanced,  (see  section  ‘time_real  time-clock’  in  LibTime  Programmer’s  Manual). 


3.5  sched Jn voke _stm time _fun ctions_o nee 
void  sch*d_invoke_aiatima_functions_onc*() 

ached.invoke.aiatiae.f  unctiona.once  forces  the  scheduler  to  invoke  all  pending  simulation 
time  functions  then  return.  That  is,  all  functions  that  have  been  scheduled  to  be  invoked  at  or  before 
the  simulation  time  achad_invok*_8iBtiaa.functions_once  is  called  will  be  invoked.  The  time 
used  is  that  from  tiaa.aiaulajion.tiaa.  No  calls  are  made  to  time_advanca_aiBulation_dock 
so  simulated  time  is  not  advanced,  (see  section  ‘time_realtimejdock’  in  LibTime  Programmer’s 
Manual). 


3.6  sched^deferred.fncl 


SCHED.FHCL.PTR  sch*d_daf*rr*d_fncl(func,  delay.maecs,  group, 

argtype,  arg, 
argtypa,  arg. 


void  (*func)(); 
uint32  dalay.aaacs ; 


A.EKD) 
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int32  group; 
int32  nrgtype ; 
argtype  arg; 

‘func’  Specifies  the  function  to  call. 

‘delay.asecsv 

Specifies  the  real  time  (in  milliseconds)  delay  before  calling  this  function. 

'group’  Specifies  a  group. 

‘argtype’  Specifies  the  type  of  each  argument.  Chosen  from  the  set:  AJNT,  A.DOUBLE, 
AJPTR,  AJ5HORT,  A.CHAR,  A.FLOAT  (defined  in 
common/indude/global/stdext.h). 

‘arg’  Argument  to  the  function. 

sched.deferred.fncl  calls  the  specified  function  after  the  specified  delay  (as  measured  against 
libtime’s  re&ltime  clock).  The  group  (typically  a  vehicle  ID)  can  be  used  later  to  remove  the 
function  (see  Section  3.10  [sched'cancel'&cl‘group],  page  9). 

A  zero-duration  delay  is  defined: 

•define  SCHED.ASAP  0 


which  can  be  used  to  invoke  a  function  as  soon  as  the  current  thread  completes  its  execution. 


Up  to  four  arguments  are  permitted. 


See  Section  3.7  [sched'simtime'fncl],  page  7. 


3.7  sched_simtime_fncl 


SCHED.FKCL.PTR  ached.siatiiM.fncl (func,  siaulation_clock,  group, 

argtype,  arg, 
argtype,  arg. 


void  (*func)(); 
uint32  siaulation.clock; 
int32  group; 
int32  argtype ; 
argtype  arg; 


A.EJTD) 
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‘func’  Specifies  the  function  to  call. 

‘siBulation_clock’ 

Specifies  the  simulation  time  when  this  function  should  be  called  (note  this  is  not  in 
real-time). 

‘group’  Specifies  a  group. 

‘argtype’  Specifies  the  type  of  each  argument.  Chosen  from  the  set-  AJNT,  AJ50UBLE, 
A.PTR,  A-SHORT,  A.CHAR,  AJFLOAT  (defined  in 
common /include/global/stdext  .h ). 

‘arg’  Argument  to  the  function. 

8ched.aiBtiM.fncl  calls  the  specified  function  at  the  specified  simulation  clock  time  (not  a 
realtime  clock  value).  The  group  (typically  a  vehicle  ID)  can  be  used  later  to  remove  the  function 
(see  Section  3.10  [sched'cancel'fncl’group],  page  9). 

See  Section  3.6  [sched'deferred'fncl],  page  6. 


3.8  sched_periodic.fncl 


SCHED.FHCL.PTR  sched.periodic.fncl (func,  initial.delay,  period,  group, 

argtype,  arg, 
argtype,  arg, 

A.END) 

void  (efunc)O; 
uint32  initial.delay; 
uint32  period; 
int32  group; 
int32  argtype ; 
argtype  arg; 


‘func’  Specifies  the  function  to  call  periodically. 

‘initial.delay’ 

Specifies  the  real  time  delay  before  calling  this  function  the  first  time  (in  milliseconds), 
‘group’  Specifies  a  group. 

‘argtype’  Specifies  the  type  of  each  argument.  Chosen  from  the  set:  AJNT,  AJDOUBLE, 
A.PTR,  AJSHORT,  A.CHAR,  AFLOAT  (defined  in 
common/include/ global/stdext.h). 

‘arg’  Argument  to  the  function. 
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sched.periodic.fncl  calls  the  specified  function  after  the  specified  initial.delay,  and  every 
period  milliseconds  thereafter  (as  measured  against  libtime’s  realtime  clock).  The  group  (typically 
a  vehicle  ID)  can  be  used  later  to  remove  the  function  (see  Section  3.10  [sched'cancel'fncl'group], 
page  9). 

Up  to  four  arguments  are  permitted. 


3.9  sched-cancel-fncl 

void  sched. cancel. fncl (fncl) 

SCHED_FHCL_PTR  fncl; 

‘fncl’  Specifies  deferred  or  periodic  function  to  cancel. 

sched.cancel.fncl  cancels  the  specified  function  (created  with  either  sched.periodic.fncl 
or  sched.deferred.fncl). 


3.10  sched.cancel-fncl-group 

void  sched.cancel.f ncl.group (group) 
int32  group; 

‘group’  Specifies  the  group. 

sched.cancel.f ncl.group  cancel  all  functions  which  were  created  with  the  specified  group 
value.  This  is  typically  used  to  cancel  all  the  functions  associated  with  a  particular  vehicle. 


3.11  sched  _change_fncl_period 


void  sched.change.fncl.period(fncl,  nev.period.msecs) 
SCHED.FMCL.PTR  fncl; 
int32  new. period. msecs ; 


‘fncl’ 


Specifies  the  periodic  function  to  change. 
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‘new.period’ 

Specifies  the  new  period. 

sched_change.fncl_peri.od  change  the  period  of  the  passed  function  (created  with 
sched.periodic.fnd)  to  the  new  period  specified. 


3.12  sched_perf_monitor_on 

void  ached.perf.monitor.on(period) 
uint32  period; 

‘period’  Specifies  interval  between  reports  (in  milliseconds). 

sched_perf  .nonitor.on  enables  performance  monitoring,  and  report  results  every  period  mil 
liseconds. 


3.13  sched_perf-monitor_off 


void  sched.perf_aonitor.offO 


8ched_perf_nonitor_off  disable  performance  monitoring. 


3.14  8ched_set_critical_performance 


void  8ched_8et_critical_performance(period,  ratio, 

under .threshold,  for.how.long, 
stress.f unction,  relief .function) 

uint32  period; 

float64  ratio; 

uint32  under. threshold ; 

uint32  for.how.long; 

void  (*stress_function)() ; 

void  (erelief. function) () ; 


‘period,  ratio,  under. threshold,  for.how.long’ 

Specify  acceptable  performance  characteristics. 
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‘stress.function’ 

Specifies  function  to  call  when  performance  becomes  unacceptable. 

‘relief  .function’ 

Specifies  function  to  call  when  performance  becomes  acceptable. 

ached_set_critical_perfonsance  sets  the  required  performance  characteristics.  If  ratio 
loops  through  the  period  ring  fail  to  sustain  a  period  of  under. threshold  for  a  duration  of 
for.hoe.long,  the  stress.function  will  be  called.  If  the  system  recovers,  the  relief  .function 
will  be  called. 
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1  Overview 


LibSelect  provides  a  generic  facility  for  making  objects  on  the  map  selectable  for  editing.  It  also 
provides  a  menu  for  system  level  editors  which  don’t  belong  as  mode  buttons  on  the  interface. 

Objects  on  the  map  are  classified  using  libSensitive  SNSTVE_CLASS  structures.  When  the 
selection  tool  is  started  (or  restarted),  it  simply  runs  through  all  the  classes  which  have  been 
registered,  and  makes  them  sensitive  to  mouse  input.  At  this  time,  it  also  installs  a  gesture  handler 
for  each,  which  will  be  called  if  the  user  clicks  on  the  object. 

Selection  is  a  SAF  GUI  mode,  and  as  such,  it  is  suspended  if  the  GUI  enters  another  mode 
(see  section  ‘sguijaddunode’  in  LibSAFGl'I  Programmer’s  Manual).  When  this  happens,  libSelect 
removes  the  gesture  callbacks  and  sensitivity  of  all  the  classes  which  it  is  managing.  The  callbacks 
and  sensitivity  are  restored  when  the  selection  tool  is  resumed. 

LibSelect  also  monitors  the  system  privilege  level  (see  section  ‘Overview’  in  LibPrivilege  Pro¬ 
grammer’s  Manual),  and  allows  selectable  classes  to  act  like  privileged  buttons. 

Finally,  libSelect  provides  support  for  seemingly  modeless  editors  which  run  in  the  context  of 
the  selection  mode.  This  is  useful  for  editors  which  the  user  may  desire  to  leave  up  whenever  no 
other  editor  is  active. 
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2  Usage 


The  software  library  ‘libselect.a’  should  be  built  and  installed  in  the  directory 
‘/comaon/lib/’.  You  will  also  need  the  header  file  ‘libselect.h’  which  should  be  installed  in  the 
directory  ‘/coanon/include/libinc/’.  If  these  files  are  not  installed,  you  need  to  do  a  ‘make’  in 
the  libselect  source  directory.  If  these  files  are  already  built,  you  can  skip  the  section  on  building 
libselect. 


2.1  Building  Libselect 

The  libselect  source  files  are  found  in  the  directory  ‘/comnon/libsrc/libselect’.  ‘RCS’  format 
versions  of  the  files  can  be  found  in  ‘/nfs/ common,  src/libsrc /libselect’. 

If  the  directory  ‘comnon/libsrc/libselect’  does  not  exist  on  your  machine,  you  should  use 
the  ‘genbuild’  command  to  update  the  common  directory  hierarchy. 

To  build  and  install  the  library,  do  the  following: 

•  cd  comnon/libsrc/libselect 
i  co  RCS/*,t 

•  make  install 

This  should  compile  the  library  ‘libselect.a’  and  install  it  and  the  header  file  ‘libselect.h’ 
in  the  standard  directories.  If  any  errors  occur  during  compilation,  you  may  need  to  adjust  the 
source  code  or  ‘Makefile’  for  the  platform  on  which  you  are.  compiling,  libselect  should  compile 
without  errors  on  the  following  platforms: 

•  Mips 

•  SGI  Indigo 

•  Sun  Sparc 


2.2  Linking  with  Libselect 

Libselect  can  be  linked  into  an  application  program  with  the  following  link  time  flags:  ‘Id 
[source  .o  files]  -L/comnon/lib  -lselect  [other  libraries]’.  If  your  compiler  does  not  sup- 
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port  ‘-L’  syntax,  you  can  use  the  archive  explicitly:  ‘Id  [source  .o  files] 
/coanon/lib/libselect .  s’. 

Libselect  depends  directly  on  the  following  libraries:  libsafgui,  libtactmap,  libsensitive,  libeditor, 
and  libprivilege. 


2.3  Examples 


The  following  is  from  the  libunits  initialization  routine.  It  demonstrates  how  to  define  a  se¬ 
lectable  class: 


/*  Make  the  sensitive  class  */ 

SMSTVE_IIIT_CLASS(edtr->snstve_class) ; 

/*  Set  the  dragging  threshold  for  selection  */ 
edtr>>snstve.class . drag. thresh  *  50; 

/*  Add  the  selectable  class.  Require  BATTLEMASTER  privilege  to 

*  select,  allov  dragging  at  select  tiae,  and  install  the  function 

*  units. selected  as  the  gesture  handler. 

*/ 

select. add.selectable (select.  Aedtr->snstve_class .  PRIV. BATTLEMASTER , 

TRUE,  units.selected,  edtr); 
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3  Functions 


The  following  sections  describe  each  function  provided  by  libselect,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


3.1  selectJnit 

void  select.initO 


select. init  initializes  libselect.  Call  this  before  any  other  libselect  function. 


3.2  select_£re&te 


S ELECT. TOOL.PTR  select_create(gui,  tactmap,  map.erase.gc,  sensitive) 
SGUI.PTR  gui ; 

TACTMAP.PTR  tactaap; 

GC  map.erase.gc; 

SISTVE.miDOW.PTR  sensitive; 

‘gui’  Specifies  the  SAF  GUI 
‘tactaap’  Specifies  the  tactical  map 

‘map.erase.gc’ 

Specifies  the  GC  which  erases  things  from  the  map 

‘sensitive’ 

Specifies  the  sensitive  window 


select. create  creates  a  selection  tool.  This  should  be  called  before  creating  other  editors  and 
tools  for  a  GUI,  so  that  the  selection  icon  appears  at  the  top  of  the  list. 


3.3  select^add .editor 


void  select.add.editor(select,  editor,  load.editor.fcn,  load  editor  ars) 
SELECT.T00L.PTR  select;  '  " 

EDT.EDIT0R.PTR  editor; 

SELECT.LOAD.EDITOR  load.editor.fcn; 
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ADDRESS  load.editor.arg; 

‘select’  Specifies  the  selection  tool 

‘editor’  Specifies  the  editor 

‘load.editor.fcn,  load.editor.arg' 

Specifies  a  function  to  call  to  load  the  editor  with  current  values  load.editor.f cn  and 
load. editor. arg  can  both  be  NULL. 

select.add.editor  adds  an  editor  to  the  list  of  editors  maintained  by  libselect.  The  library 
will  call  the  passed  load.editor.fcn  (if  non-NULL)  after  the  editor  is  brought  up  to  get  initial 
values.  This  function  can  initialize  the  editor  using  edt.load  (see  section  ‘edtjoad’  in  LibEditor 
Programmer’s  Manual). 

The  loading  function  should  be  prototyped  as  follows: 

▼oid  load. editor (editor,  user.arg) 

EDT.EDITOR.PTR  editor; 

ADDRESS  user.arg; 


3.4  select^editor^done 

▼oid  select.editor. done (select,  editor) 

SELECT. TOOL_PTR  select; 

EDT.EDITOR.PTR  editor; 

‘select’  Specifies  the  select  tod 

‘editor’  Specifies  the  editor  which  has  finished 

select.editor.done  informs  libselect  that  one  of  its  editors  (passed  to  select.add_editor) 
has  finished.  Call  this  from  the  editor's  ezit.fcn  (see  section  ‘edtjereate’  in  LibEditor  Program¬ 
mer’s  Manual). 


3.5  select_start_editor 


▼oid  select.start. editor (select,  editor) 
SELECT.TOOL.PTR  select; 
EDT.EDITOR.PTR  editor; 
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‘select’  Specifies  the  select  tool 

‘editor’  Specifies  the  editor  to  start 

select.start.editor  causes  libselect  to  start  the  passed  editor,  as  though  the  user  had  clicked 
the  editor’s  button.  WARNING:  the  load  function  is  not  invoked,  so  if  the  caller  needs  to  load  the 
editor  with  any  values,  that  should  be  done  immediately  after  this  function  returns. 


3.6  select_add .selectable 


void  select.add_selectable(select,  class,  privilege, 

dragable,  handler, function,  user.data) 
SELECT, TOOL, PTR  select; 

SMSTVE.CLASS  * class; 

PRIV, LEVEL  privilege; 

int32  dragable ; 

CALLBACK, HANDLER  handler, f unction; 

ADDRESS  user.data; 


‘select’  Specifies  the  select  tool 

‘class’  Specifies  the  libsensitive  class 

‘privilege’ 

Specifies  the  system  privilege  needed  to  select  object  of  this  class 

‘dragable’ 

Specifies  whether  the  objects  should  be  dragable  when  selected 
‘handler .function,  user.data’ 

Specifies  the  function  to  install  as  the  sensitive  gesture  callback  (see  section  ‘Class 
Definition’  in  LibSensitive  Programmer’s  Manual) 


select_add.selectable  registers  a  sensitive  class  with  libselect,  along  with  arguments  to 
callback.register_handler  which  will  be  installed  when  the  select  tool  is  enabled. 


3.7  select^allow .selection 


void  select.allos.selectionCselect,  do. allow) 
SELECT.T00L.PTR  select; 
int32  do, allow; 


‘select’  Specifies  the  select  tool 
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4 do. allow’ 

Specifies  whether  to  allow  selection  or  not 

••lect.allow.aolection  enables  handlers  and  sensitivity  for  all  objects.  This  can  be  called 
from  another  mode  to  allow  selection  from  within  that  mode.  Note  that  there  may  be  surprising 
consequences  if  objects  on  the  map  are  sensitive  for  other  reasons.  Also,  multiple  calls  to  allow  will 
register  handlers  multiple  times,  so  be  sure  to  disable  selection  once  for  each  enabling. 
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1  Overview 


Libsema  provides  a  simple  abstraction  for  controlling  access  to  shared  resources  between  mul¬ 
tiple  processes  on  a  single  hardware  platform.  Libsema  uses  semaphores  to  implement  a  locking 
mechanism  which  allows  multiple  simultaneous  readers  or  a  single  writer  to  access  the  resource 
being  locked. 

A  common  use  for  the  libsema  read/write  locks  is  to  control  access  to  a  block  of  shared  memory 
being  used  for  interprocess  communications  between  processes  on  the  same  hardware  platform. 

Libsema  can  use  System  V  semaphores  (Sun  SPARC  and  SGI)  or  IRIX  REACT  semaphores 
(SGI  only)  to  implement  the  read/write  locks.  The  choice  of  semaphore  abstractions  is  provided 
as  a  flag  passing  to  the  semaJnitQ. 
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2  Functions 


The  following  sections  describe  each  function  provided  by  libsema,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  semaJnit 

int32  seaa_ln.it (path,  nreaders,  semasys5) 
char  *path; 
int32  nreaders ; 
int32  seaasysS; 

‘arena_path’ 

For  the  IRIX  REACT  semaphores,  “path"  specifies  a  UNIX  file  system  path  to  an 
existing  file  which  is  used  to  initialize  the  semaphore  abstraction. 

‘nreaders’ 

Specifies  the  maximum  number  simultaneous  read  locks  which  will  be  allowed  on  the 
read/write  locks.  That  is,  semaphores  are  initialize  with  a  value  of  "nreaders"  when 
they  are  created. 

‘semasysS’ 

Specifies  whether  to  use  System  V  semaphores  (semasysS  =  1  )  or  IRIX  REACT 
semaphores  (semasys5  =  0).  The  default  is  to  use  IRIX  REACT  semaphores. 

seaa_init  initialized  the  libsema  library.  When  using  IRIX  REACT  semaphores,  the  "path" 
argument  must  specify  a  UNIX  file  system  path  to  an  existing  file.  This  file  is  used  to  initialize  the 
"arena"  from  which  IRIX  REACT  semaphores  are  allocated.  When  using  System  5  semaphores, 
this  argument  is  ignored.  The  "nreaders"  parameter  specifies  the  maximum  number  of  simultaneous 
read  locks  which  will  be  allowed  on  libsema  read/write  locks  before  a  block  will  occur. 


2.2  sema.jcreate_rwlock 

SEMA.RWLOCK  sema_create_rwlock() 

sema. create. rvlock  creates  new  read/write  lock  with  a  value  equal  to  the  nreaders  specified 
in  the  sena.init  function.  This  lock  is  passed  back  to  the  caller  as  a  return  value. 
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2.3  sema_destroy_rwlock 


int32  seaa.destroy.rvlock(rvlock) 
SEMA.RULOCK  rvlock; 


‘rvlock’  Specifies  the  read/ write  lock. 


Destroys  the  specified  read/write  lock. 


2.4  sema_rwlock_op 

int32  aaaa.rvlock.op (rvlock ,  lock.op) 

SEMA. RWLOCK  rvlock; 

SEMA.OPTYPE  lock.op; 

Specifies  the  read/write  lock. 

Specifies  the  operation  to  be  performed  on  the  lock.  The  set  of  operations  includes: 
SEHA.READ.LOCK.OPTYPE  Lock  for  reading 
SEMA.WRITE.LOCK.OPTYPE  Lock  for  writing 
SEMA.READ.UHLOCK.OPTYPE  Unlock  for  reading 
SEMA.WRITE.UWLOCK.OPTYPE  Unlock  for  vriting 

aeaa.rvlock.op  performs  the  specified  lock  operation  on  the  specified  read/write  lock.  The 
SEMA_READ_LOCK_OPTYPE  decrements  the  value  of  the  lock  by  1.  If  the  value  goes  neg¬ 
ative,  the  calling  process  is  blocked  until  the  value  of  the  lock  goes  positive  again.  Similarly, 
the  SEMA-WRITE-LOCKjOPTYPE  decrements  the  value  of  the  lock  by  a  number  equal  to  the 
maximum  number  of  readers  allowed  (see  aeaa_init).  If  the  value  of  the  read/write  lock  goes 
negative  the  calling  process  is  blocked.  The  SEMAJtEAD.UNLOCK.OPTYPE  increments  the 
value  of  the  lock  by  1.  This  has  the  potential  of  unblocking  a  process  waiting  on  the  lock.  The 
SEMA.WRITE.UNLOCK.OPTYPE  increments  the  value  of  the  lock  by  a  number  equal  to  the 
mayimam  number  of  readers  allowed.  This  has  the  potential  of  unblocking  one  or  more  processes 
waiting  on  the  lock. 


2.5  semajdump 


‘rvlock’ 

‘lock_op’ 


void  seaa.duBp_rvlock( rvlock,  string) 
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SEMA.RWLOCK  rvlock; 
char  * string; 

‘nrlock’  Specifies  the  read/write  lock. 

‘string’  Specifies  the  procedure  name 

Prints  the  current  value  of  the  specified  lock  to  "stdout". 


2.6  semaJump 

char  *sema_«rrorO 


Returns  an  error  string  for  the  last  error  in  the  libsema. 
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1  O  verview 


LibSensitive  provides  a  facility  for  managing  moose-sensitive  objects  in  an  X  windows  environ¬ 
ment.  It  was  designed  to  fulfill  the  following  requirements: 

•  Allow  sensitive  objects  to  be  rectangular,  circular,  or  linear. 

•  Allow  rapid  modification  of  sensitive  objects. 

•  Allow  objects  to  be  hot  (to  automatically  highlight  when  the  mouse  pointer  passes  over  them ). 
without  using  a  significant  amount  of  CPU. 

•  Allow  objects  to  respond  to  any  combination  of  mouse  buttons. 

•  Allow  thousands  of  simultaneous  sensitive  objects  without  significantly  impacting  performance. 

•  Allow  application-defined  classification  of  objects  to  facilitate  changes  to  sensitivity  and  button 
responses  of  many  objects  at  once. 

•  Allow  sensitive  object  to  be  draga ble  (mouse  movement  beyond  a  certain  threshold  drags  the 
highlight). 

•  Report  the  amount  of  dragging  relative  to  the  initial  mouse-press  location,  in  addition  to 
reporting  the  absolute  screen  location  (this  allows  an  object  to  be  picked  and  dragged  by  any 
point,  instead  of  only  by  its  origin). 

An  application  creates  sensitive  objects  using  two  structures:  SRSTVE.CLASS  and 
SISTVE. OBJECT.  The  class  defines  the  sensitivity  attributes  for  a  set  of  objects;  the  object  defines 
the  shape  of  a  single  object  in  a  class. 


1.1  Class  Definition 

A  sensitive  class  is  defined  by  an  application  simply  by  allocating  a  structure  and  using  it. 
Every  object  must  belong  to  a  class,  but  an  application  could  put  each  object  in  its  own  class.  The 
SRSTVE.CLASS  structure  is  defined  as  follows: 


typedef  struct  snstve.class 

unsigned  sensitive  :  1; 

unsigned  hot  :  1; 

unsigned  dragable  :  1; 

unsigned  drag. thresh  :  6; 

unsigned  buttons  :  5; 

CALLBACK.EVEIT.PTR  excited; 
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CALLBACK.EVEIT.PTR  gesture; 

>  SISTVE. CLASS; 

sensitive 

Specifies  whether  objects  in  the  class  should  be  considered  active.  It  is  faster  to  change 
the  sensitivity  attribute  of  a  class  than  to  frequently  remove  and  add  it  from  the  table. 

hot  Specifies  whether  objects  in  the  class  should  highlight  when  the  mouse  passes  over 

them. 

dragable  Specifies  whether  the  user  can  drag  class  objects  around  (represented  by  dragging  the 
highlight  box).  Note  that  dragging  an  object  does  aot  change  the  object;  it  is  the 
application’s  responsibility  to  act  on  the  dragging. 

drag. thresh 

When  dragable  is  TRUE,  this  specifies  the  amount  of  mouse  movement  necessary  before 
dragging  occurs  (this  is  to  help  avoid  accidental  dragging). 

buttons  Indicates  which  mouse  buttons  should  trigger  the  gestures  callback;  to  get  X  button 
n,  set  bit  [1  «  n];  as  in  X,  button  0  (the  low-order  bit)  will  get  any  button. 

excited  If  hot  is  TRUE,  this  specifies  a  function  to  call  when  the  cursor  passes  into  or  out  of  an 
object  in  this  class. 

gesture  Specifies  a  function  to  call  when  the  mouse  is  pressed,  dragged,  or  released  over  an 
object  in  this  class.  The  drag  and  release  phases  will  not  be  invoked  unless  the  pressed 
phase  was  invoked  for  an  object. 

The  excited  and  gesture  callbacks  should  both  be  defined  as  follows: 

void  callback (window,  action,  call. data,  callback. arg) 

SISTVE. HI IDOV.PTR  window; 

SISTVE.ACTIQI  action; 

SISTVE.CALL. DATA  * call. data; 

ADDRESS  callback. arg; 

The  action  is  one  of  the  following: 

SISTVE. EXCITED 

The  mouse  entered  a  hot  object. 

SISTVE. UIEXCITED 

The  mouse  left  a  hot  object. 

SRSTVE.PRESS 

The  user  clicked  on  a  sensitive  object. 
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SMSTVE.NOTIQH 

The  user  dragged  a  clicked-in  object  (regardless  of  whether  the  object’s  dragable  field 
is  set). 

SRSTVE.RELEASE 

The  user  released  a  clicked-in  object. 

The  call.data  is  defined  as  follows: 


typedsf  struct 

snstve.call.i 

SISTVE. CLASS  *class; 

int32 

instance ; 

ADDRESS 

ussr.data 

int32 

button; 

uintl6 

screen.! ; 

uintl6 

screen. y; 

intlO 

zoff; 

intl6 

yoff; 

>  SISTVE. CALL. DATA ; 


class 

instance 

user.data 

Application-defined  identification  of  the  affected  object.  The  class  will  be  NULL,  and 
the  instance  will  be  -1  if  the  no  object  was  indicated  (such  as  a  click  on  the  screen 
which  did  not  touch  an  object). 

button  Specifies  which  button  was  used  ( 1-5),  or  0  when  action  is  SISTVE. EXCITED  or  SXSTVE.UHEXCITED. 

screen.! 

screen,  j  Specifies  the  location  of  the  action  in  screen  coordinates, 
zoff 

yof  f  Specifies  the  location  of  the  action  relative  to  where  the  mouse  press  occured  (this  is 
always  0,0  when  action  is  SHSTVE.PRESS). 


LibSensitive  provides  a  macro  to  facilitate  use  of  the  class  structure:  SHSTVE.IRIT.CLASS.  This 
macro  zero’s  out  all  the  fields  of  the  structure,  and  creates  the  two  libCallback  events  (see  section 
‘callbackjdefinejevent’  in  LibCallback  Programmer’s  Manual). 


1.2  Object  Definition 


Object  definition  occurs  through  the  use  of  e  template  structure.  The  application  creates  a 
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SNSTVE.OBJECT  structure  which  represents  the  object,  then  passes  it  to  libSensitive  for  processing. 
When  libSensitive  returns,  the  application  may  keep  the  structure  or  free  it  immediately:  libSensi¬ 
tive  keeps  no  pointers  to  the  structure  (except  for  the  class  pointer  referred  to  within  the  structure). 
Each  object  is  defined  as  follows: 


typedef  struct  snstve.object 

< 

SNSTVE.KIKD  kind; 

SMSTVE.CLASS  *class ; 
int32  instance ; 

ADDRESS  user.data; 

union 

{ 

struct 

{ 

intl6  x; 
intl6  y; 
intl6  width; 
intl6  height; 

>  rect; 
struct 

intl6  x; 
intl6  y; 
intl6  radius; 

>  circle; 
struct 

intl6  xO; 
intl6  yO; 
intld  xl; 
intl6  yl; 
intl6  width; 

>  line; 

>  attr; 

/*  other  fields  which  the  application  should  consider  private . . . 
*/ 

>  SMSTVE. OBJECT; 


class  Specifies  the  application-defined  classification  of  the  object  (see  (undefined)  [Class  Def¬ 
inition],  page  (undefined)). 

instance  Specifies  the  application-defined  instance  of  the  application-defined  class  (this  is  passed 
back  to  the  application  in  callbacks).  The  combination  of  class  and  instance  must 
uniquely  identify  an  object. 
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user.data 

Specifies  an  arbitrary  piece  of  data  which  the  application  associates  with  the  object. 

This  is  provided  in  addition  to  the  instance  field  to  facilitate  libraries  like  libTactMap 
which  need  to  place  special  meaning  in  the  instance  attribute,  yet  would  like  applica¬ 
tions  to  be  able  to  define  objects. 

kind  Specifies  the  type  of  object.  It  should  be  one  of  the  following: 

SNSTVE.  RECTANGLE 

A  rectangle  starting  at  attr.rect.x,  attr.rect.y,  with  width  of 
attr.rect.  width  pixels  and  height  of  attr.rect. height  pixels.  All  units 
are  in  screen  coordinates,  and  negative  numbers  are  acceptable. 

SHSTVE.CIRCLE 

A  circle  centered  at  attr.circla.x,  attr  .circle,  y,  with  radius  of  attr.  circle,  rad 
pixels.  All  units  arc  in  screen  coordinates,  and  negative  numbers  are  ac¬ 
ceptable. 

SHSTVE.CIRCLE 

A  line  from  attr. line. xO,  attr. line. yO  to  attr. line. xO, 
attr. line. yO,  with  width  attr. line. width.  All  units  are  in  screen  co¬ 
ordinates,  and  negative  numbers  are  acceptable. 
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2  Usage 


The  software  library  ‘libsensitive. a’  should  be  built  and  installed  in  the  directory 
‘/coaaon/lib/’.  You  will  also  need  the  header  file  ‘libeensitive.h’  which  should  be  installed  in 
the  directory  ‘/coaaon/include/libinc/’.  If  these  files  are  not  installed,  you  need  to  do  a  ‘make’ 
in  the  libsensitive  source  directory.  If  these  files  are  already  built,  you  can  skip  the  section  on 
building  libsensitive. 


2.1  Building  Libsensitive 

The  libsensitive  source  files  are  found  in  the  directory  ‘/coBson/libsrc/libsensitive’.  ‘ECS’ 
format  versions  of  the  files  can  be  found  in  7nfs/coamon_src/libsrc/libsensitive’. 

If  the  directory  ‘cotmon/libsrc/libssnsitive’  does  not  exist  on  your  machine,  you  should  use 
the  ‘genbuild’  command  to  update  the  common  directory  hierarchy. 

To  build  and  install  the  library,  do  the  following: 

S  cd  conaon/libarc/libsensitive 
•  co  RCS/*,v 
i  make  install 

This  should  compile  the  library  ‘libsensitive. a’  and  install  it  and  the  header  file 
‘libsensitive .  h’  in  the  standard  directories.  If  any  errors  occur  during  compilation,  you  may  need 
to  adjust  the  source  code  or  ‘Makefile’  for  the  platform  on  which  you  are  compiling,  libsensitive 
should  compile  without  errors  on  the  following  platforms: 

•  Mips 

•  SGI  Indigo 

•  Sun  Sparc 


2.2  Linking  with  Libsensitive 

Libsensitive  can  be  linked  into  an  application  program  with  the  following  link  time  flags:  ‘Id 
[source  .o  files]  -L/cooaon/lib  -lsensitive  -lXt  -1X11  -In’.  If  your  compiler  does  not  sup- 


8 


LibSensitive  Programmer’s  Guide 


port  ‘-L’  syntax,  you  can  use  the  archive  explicitly:  ‘Id  [source  .o  files] 
/conmon/lib/libsenaitive .  a’. 

Libsensitive  depends  on  X  windows. 


2.3  Examples 

The  test  program  ‘test .  c’  in  the  libsensitive  directory  shows  usage  of  most  libsensitive  functions. 

The  program  operates  as  follows: 

•  The  program  fills  the  window  with  lines,  rectangles  and  circles.  All  of  these  objects  are  hot. 
Some  of  these  objects  (orange  lines,  green  circles,  and  red  rectangles)  also  have  dragable 
highlights. 

•  The  program  clears  the  screen  and  generates  a  new  screen  full  of  objects  every  30  seconds. 

•  The  program  makes  non-dragable  circles  and  rectangles  insensitive  15  seconds  after  regenera¬ 
tion. 

•  When  a  mouse  press  or  release  event  occurs  on  a  sensitive  object,  or  when  any  mouse  event 
occurs  on  the  screen,  the  parameters  of  that  event  are  printed  out. 

•  Rectangles  respond  to  the  left  button,  circles  respond  to  the  middle  and  right  buttons,  and 
lines  respond  to  any  button. 

•  Orange  lines,  green  circles,  and  red  rectangles  can  be  dragged  to  a  new  location. 

•  Two  circles  move  around  the  screen.  The  green  one  can  be  dragged  to  a  new  location. 
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3  Functions 


The  following  sections  describe  each  function  provided  by  libsensitive,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


3.1  snstveJnit 

▼old  snstvs.initO 

anstve.init  initializes  libsensitive.  Call  this  before  any  other  libsensitive  functions. 


3.2  SNSTVE JNIT.CLASS 

void  SHSTVE_IHIT_CLASS (class) 

SMSTVE. CLASS  class; 

Class’  Specifies  the  class  structure  (not  a  pointer)  to  initialize. 

SNSTVE.INIT.CLASS  is  a  macro  which  initializes  a  class  structure.  Once  objects  h  /e  been 
created  in  a  class,  the  fields  should  only  be  modified  using  the  function  snstve.set.class  and 
snstve.set.dass.buttons. 

See  (undefined)  [Class  Definition],  page  (undefined). 

See  (undefined)  [snstve'set 'class],  page  (undefined). 

See  (undefined)  [snstve'set'class'buttons],  page  (undefined). 


3.3  snstve_mis8_caUback 

CALLBACK_EVENT_PTR  sns t ve.miss _ callback ( window) 
SHSTVE.WIHDOW.PTR  window; 


‘window’  Specifies  the  senstitive  window. 
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snstve_aiss. callback  returns  the  libcallback  event  handle  which  is  fired  when  the  mouse  is 
pressed,  dragged  or  released  on  the  window,  outside  the  bounds  of  any  sensitive  object. 


3.4  snstve^create 

SHSTVE.WIHD0tf.PTR  snstve.create ( widget ,  drav.gc,  erase.gc) 

Widget  vidget; 

GC  drav.gc ; 

GC  erase.gc ; 

‘vidget’  Specifies  the  widget  where  input  is  received  and  highlights  are  drawn 
‘drav.gc’  Specifies  the  GC  for  drawing  highlights 

‘erase.gc’ 

Specifies  the  GC  for  erasing  highlights 

snstve. create  creates  a  sensitive  window.  This  is  passed  to  all  other  libsensitive  routines.  The 
GCs  are  used  to  draw  and  erase  highlight  (hot)  boxes.  Note  that  the  erase  should  either  clear 
the  color  plane  used  by  the  drav,  or  it  should  be  tiled  with  the  underlying  picture.  Note  that  it 
is  safe  to  create  more  than  one  sensitive  window  acting  on  a  single  X  window,  however  it  could  be 
confusing  to  the  user  (since  overlapping  objects  could  be  hot  in  both). 


3.5  snstvejrefresh 

void  snstve.refresh(vindov) 

SHSTVE.VIHDOtf.PTR  vindov; 

‘window’  Specifies  the  sensitive  window 

snstve.refresh  redraws  the  current  highlight,  if  any  (call  this  after  any  operation  which  clears 
the  screen). 


3.6  snstve_add .object 


void  snstve_add.object( vindov,  object) 
SHSTVE.WIHDOW.PTR  vindov; 

SHSTVE. OBJECT  'object; 
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‘window’  Specifies  the  sensitive  window 

‘object’  Specifies  the  object  to  add 

snstvs.add.obj set  adds  an  object  to  the  sensitive  window.  Note  that  the  object  structure  is 
copied  into  the  window;  the  pointer  is  not  saved  by  libsensitive. 


3.7  snstvejremove-ob ject 

int32  snstvs.rsaova.objsct (window,  z,  y,  class,  instance) 

SNSTVE. WIIDOV.PTR  window; 
intl6  x,  y; 

SNSTVE.CLASS  *class; 
int32  instance; 

‘window’  Specifies  the  sensitive  window 

‘x,  y’  Specifies  the  location  of  the  object 

‘class’  Specifies  the  application-defined  class  of  the  object 

‘instance’ 

Specifies  the  application-defined  instance  of  the  object 

snstve.reaove.obj  ect  finds  and  removes  an  object  from  the  sensitive  window.  The  passed 
location  should  be  any  point  within  the  bounding  box  of  the  object.  Note  that  snstvs.dsar  and 
snstve. clear. class  are  much  faster  than  removing  a  number  of  objects  one  at  a  time.  The  return 
value  is  1  for  success,  0  if  the  object  could  not  be  found. 

See  (undefined)  [snstve' clear],  page  (undefined). 

See  (undefined)  [snstve'dear'class],  page  (undefined). 


3.8  snstve-changeuob ject 


int32  snstws.changs.obj set (window,  x,  y,  objsct) 
SHSTVE.VHDOV.PTR  window; 
intie  x,  y; 

SNSTVE. OBJECT  *objsct; 


‘window’  Specifies  the  sensitive  window 

‘x,  y’  Specifies  the  old  location  of  the  object 
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‘object’  Specifies  the  object  variables 

snstve.change.objact  finds  and  relocates  an  object  in  the  sensitive  window.  The  passed 
location  should  be  any  point  within  the  current  bounding  box  of  the  object  (where  it  is  now,  not 
where  it  is  going).  Note  that  when  a  hot  object  is  changed  with  this  routine,  the  highlight  may 
be  retained  if  the  object  is  still  under  the  pointer  after  the  change.  This  would  not  be  true  if  the 
object  were  removed  with  snstve.remove.obj  ect  and  re-added  with  snatve.add.objact.  Also, 
an  object  which  is  currently  hot  will  only  stay  hot  if  it  is  The  return  value  is  1  for  success,  0  if  the 
object  could  not  be  found. 

See  (undefined)  [snstve* remove' object],  page  (undefined). 

See  (undefined)  [snstve'add'object],  page  (undefined). 


3.9  snstve_clear.jcla88 

void  snstve.clear.dass  (window,  class) 

SNSTVE. HI NDOW.PTR  window; 

SHSTVE.CLASS  *class; 

‘window’  Specifies  the  sensitive  window 

‘class’  Specifies  the  class  to  clear 

snstve.clear.dass  clean  the  sensitive  window  of  all  objects  of  a  given  application-defined 
class  (this  is  much  faster  than  removing  objects  one  at  a  time). 

See  (undefined)  [snstve' remove’object],  page  (undefined). 

See  (undefined)  [snstve'clear],  page  (undefined). 


3.10  snstvejclear 

void  snstve.clear(window) 
SNSTVE. WINDOW.PTR  window; 


‘window’  Specifies  the  sensitive  window 
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snstve..  clear  clears  the  entire  sensitive  window  (this  is  much  faster  than  removing  objects  one 
at  a  time,  or  a  class  at  a  time). 

See  (undefined)  [snstve*  remove' object],  page  (undefined). 

See  (undefined)  [snstve*  clear 'class],  page  (undefined). 


3.11  snstve.set_cl&8s 


void  snstve.set. class (window,  class,  sensitive,  hot,  dragable) 
SBSTVE.WIMDOW.PTR  window; 

SHSTVE_ CLASS  'class; 

uint32  sensitive; 

uint32  hot; 

uint32  dragable; 


‘window’  Specifies  the  sensitive  window 

‘class’  Specifies  the  application-defined  class 

‘sensitive’ 


Specifies  whether  the  class  should  be  sensitive 
‘hot’  Specifies  whether  the  class  should  be  hot 

‘hot’  Specifies  whether  the  class  should  be  dragable 


snstve.set.class  sets  the  sensitivity  attributes  for  all  objects  of  a  given  application-defined 
class. 


3.12  snstve_aet.jcla88_buttonB 


void  snst^.set.class.buttonsCwindow,  class,  remove,  add) 
SMSTVIL WIMDO V.PTR  window; 

SMSTVE.CLASS  *dass; 
uint 16  remove ; 

uintie  add; 


‘window’  Specifies  the  sensitive  window 

‘class’  Specifies  the  application-defined  class 

‘remove’  Specifies  the  buttons  to  remove 
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'add'  Specifies  the  buttons  to  add 

snstve.eet.claee. buttons  sets  the  buttons  values  for  all  objects  of  a  given  application-defined 
class,  using  the  operation: 


nev.buttons  »  (old_ buttons  t  ’remove)  i  add 
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1  O  vervie w 


Sensors  is  a  SAF  components  class.  The  purpose  of  a  components  class  is  to  define  a  common 
set  of  functions  which  are  invoked  on  instances  of  that  class,  and  the  semantics  of  those  functions. 
Other  than  defining  these  functional  semantics,  components  classes  don’t  actually  do  anything. 

Access  to  sensors  functions  is  achieved  through  macros  defined  by  libsensors.  These  macros 
invoke  aspnt. invoke  with  a  code  number  which  identifies  the  function  to  run.  Libcomponents 
then  runs  this  function  for  the  particular  sensor  model  via  a  jump  table. 

The  table  below  shows  how  the  sensors  component  relationships  have  been  currently  imple¬ 
mented  via  the  ModSAF  library  structure. 

specific  libraries  generic  library  architectural  library 

libradar  libsensors  libcomponents 

libvisual  libsensors  libc opponents 

As  mentioned  above,  libsensors  requires  the  services  of  libcomponents,  an  architectural  library 
which  provides  a  level  of  abstraction  away  from  the  specific  component  interfaces.  When  the 
ModSAF  application  gets  set  up  to  run,  the  libsensors  initialization  process  directs  libcomponents 
to  define  a  sensors  component  class.  This  information  enables  libcomponents  to  define  a  structure 
to  accommodate  all  the  sensor  instantiations  a  simulated  object  is  allowed  to  have.  The  libsensors 
.  initialization  process  also  tells  libcomponents  the  number  of  its  defined  sensor  interface  functions. 
This  enables  a  simulated  object’s  user  data  to  be  allocated  enough  space  to  hold  the  address  of 
each  of  the  interface  functions  defined  in  libsensors. 

The  parametric  data  of  libcomponents  identifies  each  component  that  needs  to  be  modeled  when 
a  vehicle  is  simulated.  For  example,  a  component  entry  for  a  T72  tank  might  look  like  this:  (see 
the  file  named  USSR_T72M.params.rdr) 

(SM.Components  (bull  SM.TraekedHull) 

(turret  SILGenericTurret) 

( machine-gun  [SN.BallisticGun  I  0]) 

(main-gun  [SM.BallisticGun  I  1]) 

(visual  SM_ Visual)) 

A  T72M  simulated  vehicle  (which  belongs  to  the  safobj  class)  will  have  component  sub-class  data 
that  tells  the  ModSAF  software  to  maintain  a  structure  that  includes  one  libvisual  instantiation. 
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Since  an  application  will  interface  to  libvisual  or  libradar  through  libsensors,  a  tank's  sensor 
commands  (which  are  performed  by  libvisual)  and  an  airplane’s  sensor  commands  (which  are  per¬ 
formed  by  libradar)  are  both  issued  via  the  interface  defined  by  libsensors.  A  command  to  change 
viewing  controls  is  therefore  the  same  whether  the  sensing  component  is  a  tank  commander’s  sight 
or  an  airplane’s  radar.  What  is  different  are  the  actual  values  used  to  set  the  controls  and  those  val¬ 
ues  are  passed  as  input  to  the  function.  Similarly,  an  application  can  obtain  information  about  the 
state  of  any  of  its  sensors  though  the  libsensors  interface.  The  table  below  shows  the  relationship 
between  the  specific  and  generic  library  for  the  sensors  component. 

Instantiations  of  Belong  to  generic  Have  a  coaaand 

of  the  library:  component  class:  interface  defined  in: 


libradar  aensors  libsensors 

libvisual  sensors  libsensors 

The  interface  to  libsensors  is  defined  in  its  public  header  file  (libsensors.h).  This  inter&ce  lets 
an  application  set  sensor  controls  or  get  sensor  information  without  knowing  which  specific  sensor 
model  is  being  used.  Applications  interface  to  the  radar  model  or  visual  model  primarily  through 
the  macros  defined  in  libsensors.  These  macros  map  to  functions  which  are  invoked  on  instances 
of  the  sensors  sub-class  (such  as  the  libradar  component  instantiated  for  an  airplane  or  a  libvisual 
component  instantiated  for  a  tank). 

One  interface  for  controlling  a  sensor  is  the  SEMSORS.SET. ABSOLUTE  macro  which  maps  to  a 
function  that  sets  the  direction  of  attention,  magnification,  and  scan  parameters  for  the  sensor.  A 
possible  definition  for  this  macro  is  shown  below. 


•define  SEHSORS.SET.ABSOLUTE(_v,  _c,  .a,  .a,  .a,  _w,  _h,  _vn,  _vx,  _rx) 

SEISORS.IMTERFACE  _sif ; 

_sif .u.set.abeolute.azismth  ■  .a; 

.sif.u. set. absolute, elevation  ■  .e; 

.sif .u.set.absolute. signification  ■  .a; 

.sif .u. set .absolute. half .width  ■ 

.sif .u. set. absolute. half .height  ■  _h; 

_sif .u. set. absolute. vain  ■  _vn; 

.sif .u. set. absolute. vans  ■  .vx; 

_sif .u. set. absolute. range _aax  ■  _rx; 

capnt. invoke (SEMSORS.SET.ABSOLUTE.FCH ,  _v,  _c,  t.sif); 

> 


The  SEISORS.IITERFACE  structure  defined  in  libsensors.h  is  the  structure  which  is  passed  to 
any  senson  interface  function.  This  structure  is  a  union  of  structures  that  each  define  an  argument 
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list  for  a  sensors  interface  function.  An  abbreviated  example  that  assumes  there  are  only  a  few 
interface  functions  is  shown  below.  Typically  there  will  be  many  interface  functions  and  therefore 
more  structure  definitions  in  the  union.  The  macros  hide  this  structure  from  the  users  of  these 
functions. 

typedef  struct  sensors. interface 

{ 

union 

{ 

struct  sensors.set.controls 

float64  azisuth; 
float64  elevation; 
float64  magnification; 
float64  half .width; 
float64  half. height; 
float64  vain,  vmax ; 
float64  range.max; 

>  set. absolute,  set. relative; 

struct  sensors.set.state 

SENSORS.STATE  state; 

>  set.state,  get.state; 

>  u; 

>  SENSORS. INTERFACE; 

Issuing  a  command  to  an  objects’s  sensor  component  is  done  by  invoking  one  of  the  macros 
defined  in  libsensora.  These  macros  identify  the  specific  component  function  which  needs  to  be 
called.  For  example,  invoking  the  SEISORS.SET.ABSOLUTE  macro  will  result  in  the  calling  of  the 
setjabsolute  specific  component  function.  In  the  public  header  file  of  each  generic  library,  macros 
are  associated  with  a  function  code  number  so  that  a  call  to  the  libcomponents  library  (via  the 
cmpntJnvoke  function)  will  dispatch  a  call  to  the  appropriate  function.  The  specific  component 
functions  are  defined  and  installed  by  the  specific  libraries  (libradar  and  libvisual).  In  this  case, 
both  libraries  install  a  function  with  the  same  name,  set. absolute  (there  is  no  name  conflict 
because  each  function  is  declared  static).  It  is  the  specific  function  (either  libradar’s  setjabsolute 
or  libvisual’s  set_absolute)  which  is  called  when  the  macro  is  invoked. 

Invoking  the  macro  results  in  two  actions;  (I)  setting  up  of  the  interface  structure  and  (2)  passing 
of  necessary  information  to  libcomponent.  The  macro  passes  the  vehicle  id,  component  number,  and 
function  pointer  index  to  libcomponent  so  that  the  appropriate  library  (such  as  libradar  or  libvisual) 
data  can  be  accessed.  The  requested  function  can  require  input  (such  as  an  azimuth  and  an  eleva¬ 
tion)  and/or  output  (such  as  a  setting) .  Therefore,  libcomponents  must  also  be  passed  the  address 
of  the  interface  structure  that  holds  this  data.  In  the  copnt.invoke(SE)fSORS_SET.ABSOLUTE_FCR, 
.v,  _c,  A.sif);  code  segment  shown  above,  SENSORS. SET. ABSOLUTE.FCN  serves  as  the  function 
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pointer  index,  _▼  provides  the  vehicle  id,  .cprovides  the  component  number,  and  ft.sif  provides 
the  address  for  the  function’s  argument  lists. 
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2  Examp  lea 


To  get  the  component  number  of  my  commander's  sight: 


extern  int32  cadr.sight; 

if  ((cadr.sight  ■ 

capnt_locate( vehicle. id. 

reader.get.symbol ( "commander- sight " ) ) )  »» 

CMPNT. MOT.FOUID) 

printf ("Vehicle  %d  does  not  seen  to  have  a  commander  sightXn”. 
vehicle.id) ; 

To  center  that  sight  (the  macro  is  defined  by  libsensors;  it  assembles  a  SEMSORS.IMTERFACE 
structure,  and  calls  cmpnt. invoke): 

if  (cadr.sight  !■  CMPHT. MOT. FOUND) 

SEISORS_SET.RELATIVE( vehicle. id,  cadr.sight,  0.5,  0.5,  1.0,  1.0, 

0.0,  1.0,  1.0,  0.0); 


To  get  a  list  of  vehicles  detected  by  that  sensor: 


VTAB.LIST  list; 

if  (cadr.sight  !•  CMPNT. M0T.F0UWD) 
SEMSORS.GET.SEMSED(vehicle.id,  cadr.sight,  Alist) ; 
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3  Functions 


The  following  sections  describe  each  function  provided  by  libsensors,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


3.1  sensorsJnit 

void  sensors. init (directory,  reader.flags) 
char  ^directory; 
uint32  reader.flags; 

‘directory’ 

Specifies  the  directory  where  the  constants  file  is  expected 

‘reader.flags’ 

Specifies  reader  options  (see  section  ‘reader .read’  in  LibReader  Programmer’s  Manual) 

sensora_ir4t '  tializes  libsensors.  Call  this  function  after  cnpnt.init,  and  before  any  specific 
sensor  init  Jun  U  a,.  To  simplify  definition  of  other  data  files,  libsensors  reads  a  file  of  macro 
dilutions  from  the  passed  directory  using  the  passed  reader.flags.  These  macros  define  (in  a 
libreader  format)  some  of  the  constants  defined  by  libsensors. 


3.2  SENSORSJ5ET_ABSOLUTE 

i 


void  SEKSORS.SET.ABSOLUTECvehide.id,  component .number, 

azimuth.radiana ,  elevat ion.radians , 
half _vidth_radians ,  half .height.radians , 
magnification,  vmin,  vmax,  range.max) 

int 32  vehicle. id ; 

int32  component.number; 
float64  azimuth.radiana; 
float64  elevation.radians ; 
float64  half.width.radians; 
float64  half. height.radians; 
float64  magnification; 
float64  vmin,  vmax; 
float64  range.max; 


‘vehide.id’ 

Specifies  the  vehicle  ID 
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‘component.nuaber’ 

Specifies  the  sensor  component  number 
‘azimuth. radians' 

Specifies  the  desired  azimuth  in  radians  (attachment  coordinates) 
‘elevation_radians’ 

Specifies  the  desired  elevation  in  radians  (attachment  coordinates) 

‘half _ width. radians  ’ 

For  sensors  which  have  controllable  scan  volumes  (such  as  radar)  specifies  half  the 
scan  volume  width  in  radians  (the  scan  volume  will  go  from  -half  _width_radian*  to 
♦half.sidth_radiana). 

‘height.radians’ 

For  sensors  which  have  controllable  scan  volumes  (such  as  radar)  specifies  half  the 
scan  volume  height  in  radians  (the  scan  volume  will  go  from  -half  .haight.radians 
to  ♦half .height.radians). 

‘magnification’ 

For  censors  which  have  controllable  magnification,  specifies  the  desired  magnification 
‘vnin’  For  sensors  which  can  detect  vehicles  by  relative  motion,  specifies  the  minimum  relative 
velocity  of  vehicles,  in  meters  per  second,  to  be  detected 

‘vmax’  For  sensors  which  can  detect  vehicles  by  relative  motion,  specifies  the  maximum  relative 
velocity  of  vehicles,  in  meters  per  second,  to  be  detected 

‘ranga.max’ 

Specifies  the  maximum  range-of-interest  (as  opposed  to  detection  range)  for  the  sensor  . 

SENSORS.SET. ABSOLUTE  sets  the  direction  of  attention,  magnification,  and  scan  parameters  for 
the  sensor.  Not  all  parameters  may  be  relevant  for  a  particular  sensor.  Depending  upon  the  physical 
or  psychological  detection  model,  the  direction  of  the  sensor  may  impact  whether  a  particular  target 
is  sensed.  The  direction  is  in  sensor  coordinates  (positive  elevation  is  up,  positive  azimuth  is  left), 
and  may  be  clipped  if  it  exceeds  the  limits  of  the  sensor’s  orientability. 


3.3  SENSORS J5ET -RELATIVE 


void  SEHSORS_SET_RELATIVE( vahicle.id ,  component .number, 

azimuth,  elevation,  vidth,  height, 
magnification,  vain,  vmax,  range.max) 
int32  vehicle,  id; 
int32  component.nuaber; 
float64  azimuth; 
float64  elevation; 
float64  vidth,  height; 
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float64  Magnification; 
float64  vain,  nu; 
float64  rangejuax; 

‘vehicle. id’ 

Specifies  the  vehicle  ID 
‘ coaponent.nuaber’ 

Specifies  the  sensor  component  number 
‘azimuth’  Specifies  the  desired  azimuth 
‘elevation’ 

Specifies  the  desired  elevation 

‘width’  For  sensors  which  have  controllable  scan  volumes,  specifies  the  scan  volume  width 

‘height’  For  sensors  which  have  controllable  scan  volumes,  specifies  the  scan  volume  height 
‘magnification’ 

For  sensors  which  have  controllable  magnification,  specifies  the  desired  magnification 
‘vmin’  For  sensors  which  can  detect  vehicles  by  relative  motion,  specifies  the  minimum  relative 

velocity  of  vehicles  to  be  detected 

‘vmaz’  For  sensors  which  can  detect  vehicles  by  relative  motion,  specifies  the  maximum  relative 
velocity  of  vehicles  to  be  detected 

‘range_naz’ 

Specifies  the  maximum  range-of-interest  (as  opposed  to  detection  range) 

SERSORS.SET.RELATIVE  sets  the  direction  of  attention,  magnification  and  scan  volume  for  the 
sensor.  Not  all  parameters  may  be  relevant  for  a  particular  sensor.  Depending  upon  the  physical  or 
psychological  detection  model,  the  direction  of  the  sensor  may  impact  whether  a  particular  target  is 
sensed.  All  values  are  in  the  range  0  to  1  (azimuth:counterclockwise-to-cloclcwise,  elevation:down-to- 
up,  magnification:minimum-to-  maximum,  width:minimum-to-maximum,  heigh  t:minimum-to-maximum, 
vmin:minimum-to- maximum,  vmaxtminimum- to- maximum,  range_max:minimum-to- maximum). 


3.4  SENSORS -GET  .SENSED 

void  SEISORS.GET.SEHSED ( vehicle. id ,  coaponent.nuaber,  list) 
int32  vehicle. id ; 

int32  coaponent.nuaber; 

VTAB.LIST  *list; 

‘vehicle. id’ 

Specifies  the  vehicle  ID 
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‘  component. number’ 

Specifies  the  sensor  component  number 

‘list’  Returns  the  list  of  sensed  vehicles 

SEXSORS.GET.SENSED  returns  a  list  of  sensed  vehicles.  For  visual  sensors,  the  user  data  attached 
to  each  vehicle  in  the  list  is  the  address  of  a  SENSED.VARS  structure.  It  is  mode  fully  described 
in  libvisual. 


3.5  SENSORS. GET -TARGET -VISIBILITY 


void  SEBSORS.GET.TARGET. VISIBILITY ( vehicle. id,  component. number, 

target. id,  ctdb,  result, 
intersecting.location, 
intersecting. vehicle) 


int32 

vehide.id; 

int32 

component .number ; 

int32 

target.id; 

CTDB 

*ctdb; 

float64 

* result ; 

float64 

intersect ing.locat ion [3] 

int32 

•intersecting. vehicle ; 

‘vehide.id’ 

Specifies  the  vehicle  ID 

‘  component. number’ 

Specifies  the  sensor  component  number 

‘target.id* 

Specifies  the  target  to  check  for  visibility  against 
‘ctdb’  Specifies  the  terrain  that  might  obstruct  the  target 

‘result’  Returns  the  result  of  the  visibility  check,  as  a  fraction  between  0.0  and  1.0,  inclusive 
‘intersecting.location’ 

Returns  the  location  of  the  obstruction  if  the  target  is  fully  obstructed  by  a  vehicle  or 
an  object  on  the  terrain 
‘intersecting. vehicle’ 

Returns  the  id  of  a  vehicle  obstructing  the  target  if  the  target  is  fully  obstructed  by  a 
vehicle 


SEBSORS.GET.TARGET.VISIBILITY  returns  what  fraction  of  a  target  is  visible  from  a  sensor.  If 
a  target  is  fully  obscured  (as  indicated  by  a  result  of  0.0,  intersection.location  will  contain  the 
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location  of  the  obstruction.  If  another  vehicle  is  the  cause  of  the  obstruction,  intersecting,  vehicle 
will  contain  the  id  of  the  obstructing  vehicle. 


3.6  SEN  SORS.GETJLOCATION -VISIBILITY 


void  SEVSORS.GET. LOCATION. VISIBILITY(vehicle_id,  component .number, 

location,  location.height, 
location. width,  ctdb,  result, 
intersecting_location, 
intersecting. vehicle) 

int32  vehicle. id; 

int32  component.number; 

floated  location [3] , 
f loat64  location_height , 
floated  location. width, 

CTDB  *ctdb; 
floated  *result; 

floated  intersect ing_locat ion [3] ; 
int32  * intersect ing. vehicle ; 


‘vehide.id’ 

Specifies  the  vehicle  ID 

1  component.number’ 

Specifies  the  sensor  component  number 

‘location’ 

Specifies  the  location  to  check  for  visibility  against 
‘location.height’ 

Specifies  a  height  (in  meters)  above  the  location  to  be  used  in  any  intervisibility 
calculations 

‘location. width’ 

Specifies  a  width  (in  meters)  to  be  used  in  any  intervisibility  calcula  ons 
‘ctdb’  Specifies  the  terrain  that  might  obstruct  the  target 

‘result’  Returns  the  result  of  the  visibility  check,  as  a  fraction  between  0.0  and  1.0,  inclusive 
‘  int ersect ing_locat ion’ 

Returns  the  location  of  the  obstruction  if  the  target  is  fully  obstructed  by  a  vehicle  or 
an  object  on  the  terrain 

‘intersecting. vehicle’ 

Returns  the  id  of  a  vehicle  obstructing  the  target  if  the  target  is  fully  obstructed  by  a 
vehicle 
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SEMSORS.GET.LQCATIOI. VISIBILITY  returns  what  fraction  of  a  location  is  visible  from  a  sen¬ 
sor.  If  a  location  is  fully  obscured  (as  indicated  by  a  result  of  0.0,  intersecting_location 
will  contain  the  location  of  the  obstruction.  If  another  vehicle  is  the  cause  of  the  obstruction, 
intersecting. vehicle  will  contain  the  id  of  the  obstructing  vehicle.  In  order  to  properly  model  a 
location  occupying  space  (as  opposed  to  a  point  location),  loeation.height  and  location. width 
are  used. 


3.7  SENSORS JSET 31  ODE 

void  SEVSORS.SET.MOOECvehicle.id,  component. number,  mode,  target.id) 
int32  vehicle. id; 

int32  component. numbe  r ; 

SENS0RS.M0DE  mode; 
int 32  target. id ; 

‘vehicle. id’ 

Specifies  the  vehicle  ID 

‘  component. number’ 

Specifies  the  sensor  component  numbeT 

‘mode’  Specifies  the  operating  mode  (defined  by  given  sensor) 

‘target.id’ 

Designates  a  target,  as  required  for  certain  sensor  modes. 

SENSORS.SET.MODE  sets  the  operating  mode  of  the  sensor.  This  primarily  affects  the  type  and 
number  of  targets  detected  by  the  sensor.  If  given  a  mode  it  does  not  support,  SEVSORS.SET.MODE 
will  choose  a  suitable  replacement.  Defined  modes  are  as  follows: 

SEHSORS.PULSE.SEARCH 
Pulse  search 

SENSORS.PD.SEARCH 

Puke  doppler  search 

SEHSORS.TVS.HAIUAL 

Track- While-Scan,  manual  center 

SENSORS.TWS.AUTO 

Track- While-Scan,  automatic  center 

SEVSORS.PULSE.STT 

Single-Target-Track,  puke 
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SEISORS.PD.STT 

Single-Target-Track,  pulse  doppler 


3.8  SENSORS. GET 31  ODE 


void  SEISORS.GET.MODEC vehicle. id,  component. number,  node,  target. id) 
int32  vehicle. id; 

int32  conponent.nunber ; 

SEVSORS.NODE  *mode; 
int32  * target. id; 

'vehicle.id’ 

Specifies  the  vehicle  ID 

‘component.number’ 

Specifies  the  sensor  component  number 
‘mode’  Specifies  the  operating  mode  (defined  by  given  sensor) 

‘target,  id’ 

Designates  what  target,  if  any,  has  been  designated  for  this  mode. 

SEVSORS.GET.MODE  returns  the  current  operating  mode  of  the  sensor,  which  will  either  be  the 
default  mode  or  whatever  was  last  set  in  the  last  SEKSORS.SET.HODE.  Note  that  the  target,  id 
indicates  what  target  was  designated,  and  not  whether  that  target  is  currently  bong  detected  by 
the  sensor. 


3.9  SEN SORS.GET.C APABILITIES 


void  SEISORS.GET.CAP ABILITIES (vehicle.id ,  component. number , 
az.list,  el.list,  az.lct,  el.lct, 
az.lo,  az.hi,  el.lo,  el.hi) 
int32  vehicle.id; 

int32  component .number; 

float64  **az.list,  eeel.list; 
int32  *az.lct,  *el_lct; 

float64  *az.lo,  * az.hi ,  eel.lo,  *el_hi; 


‘vehicle.id’ 

Specifies  the  vehicle  ID 
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‘conponent.nuaber’ 

Specifies  the  sensor  component  number 

‘nz.Het'  Returns  n  pointer  to  nn  array  of  legal  azimuth  half-width  settings  for  this  sensor.  These 
half-widths  are  in  radians  and  specify  a  valid  scan  volume  which  is  plus-or-minus  this 
amount  around  a  center  beam. 

‘al.lla  t  ’  Returns  a  pointer  to  an  array  of  legal  elevation  half- height  settings  for  this  sensor.  These 
half-heights  are  in  radians  and  specify  a  valid  scan  volume  which  is  plus-or-minus  this 
amount  around  a  center  beam. 

‘az.lct,  el.lct’ 

Returns  the  number  of  valid  elements  in  azJList  and  el.list,  respectively. 

‘az_lo,  az.hi’ 

Returns  the  counter-clockwise  and  clockwise  limits  that  the  azimuth  of  the  center  beam 
of  the  scan  volume  can  be  steered  to,  in  radians. 

‘•l.lo,  el_hi’ 

Returns  the  lower  and  upper  limits  that  the  elevation  of  the  center  beam  of  a  scan 
volume  can  be  steered  to,  in  radians. 

SEISORS.GET.CAP ABILITIES  returns  (by  reference)  information  about  legal  values  for  the  sen¬ 
sor’s  scan  volume  in  terms  of  half-widths  and  half-heights.  Also  returned  is  information  about  the 
orientability  of  the  scan  volume. 


3.10  SENSORS J5ET .STATE 


void  SEVSORS.SET.STATEC vehicle. id,  component. nunber, 

etate) 

int32  vehicle. id ; 

int32  conponent. nunber ; 

SEBS0RS.STA7E  state; 


‘vehide.id* 

Specifies  the  vehicle  ID 

‘component.nuaber’ 

Specifies  the  sensor  component  number 

‘state’  Specifies  the  new  state  of  the  sensor 


SEISORS.SET.STATE  sets  the  state  of  the  sensor.  This  state  is  independent  of  the  state  of  the 
vehicle  on  which  the  sensor  is  mounted.  Defined  states  are: 
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SZISOJIS.ACTIVE 

The  sensor  is  enabled 

SENSORS.XNACTIVE 

The  sensor  is  disabled 


3.11  SEN  SOUS  .GET -STATE 


void  SENSORS.GET.STATEC vehicle. id,  component .number, 

state) 

int32  vehicle. id ; 

int32  component . number ; 

SENSORS.STATE  estate; 


‘vehicle.id’ 

Specifies  the  vehicle  ID 

‘  component .number  ’ 

Specifies  the  sensor  component  number 

‘stats’  Returns  the  current  state  of  the  sensor 

SEMSQRS.GET.STATE  returns  (by  reference)  the  state  of  the  sensor.  This  state  is  independent  of 
the  state  of  the  vehicle  on  which  the  sensor  is  mounted.  Defined  states  are: 


SENSORS. ACTIVE 

The  sensor  is  enabled 

SERSORS.IIACTIVE 

The  sensor  is  disabled 


3.12  SENSORS-GET-TARGET.INFO 


void  SENSORS. GET. TARGET. INFO ( vehicle.id ,  component. number, 
target .id,  angular.size,  angle.to.edge) 
int32  vehicle.id; 

int32  component. number; 

int32  target. id; 

float64  *angular.size; 

float64  *angle_to.edge; 
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‘vehicle.id’ 

Specifies  the  vehicle  ID 
‘  coaponent.nuaber’ 

Specifies  the  sensor  component  number 

’target. id’ 

Specifies  the  target  to  check 
‘angular.size’ 

Returns  the  angular  size  of  the  target  (in  square  radians) 

’angle. to.edge’ 

Returns  the  angle  (in  radians)  between  the  target  and  the  nearest  edge  of  the  viewport 
(or  gimbal  limit). 

SEXSORS.GET.TARGET.IIFO  returns  (by  reference)  information  about  a  specified  target  from  the 
viewpoint  of  the  sensor. 
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1  Overview 


Libshmqueue  implements  a  simple  mechanism  for  doing  interprocess  communication  between 
multiple  processes  on  the  same  hardware  platform.  Libshmqueue  implements  a  ring-buffer  of  data 
entries  (i.e.  data  packets)  which  can  be  written  to  and  read  from  with  a  minimum  blocking  time. 
Multiple  processes  can  read  from  and  write  to  the  table. 

Libshmqueue  uses  (2  ♦  <Nreaders>)  semaphores,  where  Nreader  is  the  number  of  readers. 

To  prevent  a  reader  from  catching  up  writers  in  a  ring  buffer,  the  address  of  the  next  write  entry 
is  kept  in  the  ring  buffer  header  and  a  writer  semaphore  is  used  to  protect  the  address.  A  writer 
takes  the  writer  semaphore  to  read  the  next  write  entry  address,  then  increases  it  and  releases  the 
semaphore  after  writing.  A  reader  takes  the  writer  semaphore  for  reading  to  calculate  the  the  last 
unread  entry. 

To  prevent  writers  from  writing  new  entries  while  readers  are  reading  at  the  same  locations 
in  a  ring  buffer,  an  active  reader  table  (an  array  of  <Nreaders>  dements)  is  used  together  with  a 
semaphore  for  the  table.  In  addition,  <Nreaders>  semaphores,  the  reader  semaphore  array,  is  used. 
A  reader  follows  the  following  sequence  during  reading:  takes  the  table  semaphore  for  writing, 
searches  the  active  reader  table  for  an  empty  dement,  saves  the  index  of  the  element,  writes  the 
address  of  the  first  read  entry  to  the  table,  rdeases  the  table  semaphore,  takes  the  reader  semaphore 
of  the  index  for  reading,  reads  the  entries,  release  the  reader  semaphore,  takes  the  table  semaphore 
to  erase  the  content  of  the  dement,  rdeases  the  table  semaphore.  A  writer  follows  the  following 
sequence  during  writing:  takes  the  table  semaphore  for  reading,  if  the  next  write  entry  is  not 
listed  in  the  table  writes  the  entry  and  rdeases  the  table  semaphore,  otherwise,  rdeases  the  table 
semaphore,  takes  the  reader  semaphore  of  the  conflict  reader  for  writing,  writes  the  entry,  releases 
the  reader  semaphore. 
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2  Functions 


The  following  sections  describe  each  function  provided  by  libsema,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  shmqjnit 


void  shmq.initO 


shmq.init  initializes  the  libshmq  library.  Currently  this  procedure  is  a  no-op. 


2.2  shmq computerize 


int32  stamq.coinpute.size  (nentries,  entry.size) 
int32  nentries ; 

int32  entry.size ; 


‘nentries’ 

The  number  of  entries  in  the  shared  memory  table, 
‘entry.aize’ 

The  maximum  number  of  bytes  for  each  entry. 


shmq.conpute.size  computes  the  size  of  the  shared  memory  segment  for  the  ring  buffer. 


2.3  create  -ring-buffer 


SHMQ  shmq. create.ring. buff er( buffer,  nentries,  entry. size,  nreaders) 
ADDRESS  buffer; 
int32  nentries; 
int32  entry. size; 
int32  nreaders; 


‘buffer’  The  address  of  the  ■di.wil  m<’m«»ry  segment 
‘nentries’ 

The  number  of  entri«->  hi  » !••*  -hared  memory  table. 
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‘entry.aize’ 

The  maximum  number  of  bytes  for  each  entry. 

‘nreadera’ 

The  number  of  readers. 

shmq.craate.ring.buffer  creates  a  shared  ring.buffer.  It  is  assumed  that  the  a  System5 
shared  memory  segment  has  been  created  by  the  caller.  The  shared  memory  segment  has  enough 
space  for  a  ring_buffer  of  nentries  where  each  entry  is  entry_size  bytes  large.  The  shared  ring  buffer 
includes  a  libsema  semaphore  to  control  access  among  multiple  processes. 


2.4  shmq_de8troy-ring -buffer 

int32  ahaq_destroy_ring.buffer(ahmq) 

SHMQ  shmq; 

‘sbaq’  The  address  of  a  shared  ring  buffer. 

a hmq.deatroy.ring. buffer  deletes  the  liblock  semaphores.  The  caller  has  to  free  the  shared 
memory  segment. 


2.5  shmq jread  .entries 


int32  shmq. read. entries (shmq ,  entry.offset,  num. entry,  data.sink.fn,  usar.data) 
SHMQ  shmq; 
lnt32  *entry_of f set ; 
int32  nun. entry; 

SHMQ_DATA.SIHK.FN  data.aink.fn; 

ADDRESS  usar.data; 


‘shmq’  The  table  to  be  read. 

‘entry.offset’ 

The  offset  of  the  first  entry  to  be  read  (pass  SHMQ_FIRST_ENTRY  to  start  with). 
Returns  the  offset  of  the  next  entry  to  read 

‘nun. entry’ 

The  number  of  entries  to  be  read  from  the  ring_buffer.  1,2,...N:  N  >  "number  of  total 
unread  entries":  all  unread  entries  will  be  read.  N  <=  0:  all  unread  entries  will  be 
read. 
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‘data.sink.fn’ 

The  function  to  copy  the  data  from  the  shared  ring_buffer  to  user  data  buffer.  Should 
be  a  simple  function,  such  as  bcopy(). 

‘user.data’ 

The  address  of  the  user  data  buffer. 

shmq.read.sntriss  supports  reading  through  a  shared  memory  ring.buffer  <n>  entries 


2.6  shmq^write^entry 


int32  s hoq. write. entry (shmq,  entry,  entry.size) 
SHMQ  shmq ; 

ADDRESS  entry; 
int32  entry. s ize ; 


‘shmq’  The  address  of  a  shared  ring  buffer, 
‘entry’  The  address  of  the  entry  to  be  written. 

‘entry.size’ 

The  size  in  bytes  of  entry. 


shaq.vrite.entry  writes  a  new  entry  into  the  ring  buffer. 


2.7  shmqjdump 


void  shmq.dumpCshmq,  string,  dump.locks) 
SHMQ  shaq; 
char  * string; 
int32  dump.locks ; 


‘shmq’  The  address  of  a  shared  ring  buffer, 
‘string’  Specifies  the  procedure  name 
‘dump.locks’ 

Specifies  whether  locks  should  be  dumped 


Prints  out  a  cryptic  one-line  summary  about  the  current  state  of  the  buffer. 
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2.8  shmqjerror 

char  *  shmq_ error () 

Returns  an  error  string  for  the  last  error  in  the  libshmqueue. 
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1  O  verview 


Libshmif  implements  the  shared  memory  interface  for  the  Alias  SAF.  Libshmif  is  designed 
specifically  to  support  the  IPC  needs  of  the  AGPG  project.  In  particular,  it  is  designed  to  support 
communications  between  the  SAFSim.  the  ModSAF  Control,  and  the  DIS  Interface  process.  It 
should  NOT  be  considered  a  general  purpose  library. 

Libshmif  uses  the  services  provided  by  libsema  to  provide  read/write  locks.  It  uses  the  services 
of  libshmtbl  and  libshmqueue  to  provide  data  structures  which  are  safe  for  shared  memory. 

The  shared  memory  interface  consists  of  a  "control  structure"  which  occupies  a  System  5  shared 
memory  segment.  The  control  structure  maintains  information  about  each  of  the  "channels"  which 
make  up  the  shared  memory  interface.  Each  channel  consists  of  one  or  more  "partitions"  which 
are  used  to  communicate  a  particular  protocol  (i.e.  the  Persistant  Object  Protocol)  or  subset  of  a 
protocol  (i.e.  Entity  State  PDUs  of  the  DIS  Protocol).  Channel  partitions  are  based  on  libshmtbl 
and  libshmqueue. 

Each  process  participating  in  the  shared  memory  interface  is  allocated  its  own  channel.  The 
number  of  partitions  in  the  channel  depends  upon  the  number  of  protocols  in  which  that  process 
is  interested. 
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2  Functions 

The  following  sections  describe  each  function  provided  by  libsema,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  shmifjnit 


int32  shnif_init(appl_typa ,  nreaders) 
SHMIF. APPLTYPE  appl.type; 
lnt32  nreaders ; 


‘appl.typs’ 

The  application  type  of  the  process.  Valid  values  include:  SHMIF .DISIF .APPLTYPE, 

SHMIF  JSAFSIM.APPLTYPE,  SHMIF-MODSAF.CTL.APPLTYPE. 

‘nreaders’ 

The  maximum  number  of  processes  which  will  be  reading  from  the  shmif.  Currently  this 
number  should  be  set  to  10  (i.e.  4  SHMIFJSAFSIM-APPLTYPE,  4  SHMIF_MODSAF_CTL_APPL 
1  SHMIF  J)ISIF_APPLTYPE,  1  one  to  grow  on). 

shnif  _init  initializes  the  libshmif  library. 


2.2  shmif_open jihmif 


SHMIF.SHMIF  shnif _opan_shnif (ftok.path,  ftok.char,  nprotocols, 

protocols,  exercise,  create) 


char 

♦ftok.path; 

char 

ftok.char; 

int32 

nprotocols ; 

uint8 

♦protocols ; 

int32 

•xsreiss ; 

int32 

ersats; 

‘ftok.path’ 

Specifies  the  name  which  will  be  used  to  find  the  shared  memory  segment  containing 
the  control  structure  for  this  shared  memory  interface. 

‘ftok_char’ 

Specifies  the  name  which  will  be  used  to  find  the  shared  memory  segment  containing 
the  control  structure  for  this  shared  memory  interface. 
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‘nprotocols’ 

Specifies  the  number  of  protocols  which  will  be  included  in  the  shared  memory  interface 
channel  for  this  process. 

’protocols’ 

Specifies  the  protocols  which  will  be  included  in  the  shared  memory  interface  channel 
for  this  process. 

‘exercise’ 

The  id  of  the  exercise  in  which  this  process  is  participating.  Used  by  the  shmiLread  jentries 
function  as  a  way  of  filtering  out  data  from  unwanted  processes.  A  value  of  SHMIF  JEXERCISE  JD. 
can  be  used  to  deactivate  this  filtering. 

SAFSim  processes  are  only  involve  in  one  exercise  at  a  time.  They  will  be  reading  and 
writing  data  belonging  to  that  exercise  only. 

The  DIS  Interface,  on  the  other  hand,  is  interested  in  the  data  belonging  to  all  the  active 
exercises.  When  reading,  the  DIS  Interface  reads  from  all  SAFSim  channels  regardless 
of  exercise  id.  Similarly,  the  DIS  Interface  writes  all  data  to  the  same  channel  regardless 
of  exercise  id. 

‘create’  Indicates  that  this  process  will  act  as  a  server  creating  the  shared  communications 
control  structure  used  by  the  other  processes.  In  addition,  the  server  is  responsible  for 
freeing  up  communications  channels  left  occupied  by  processes  which  exit  abnormally. 

shaif _open_shaif  installs  or  creates  a  shared  memory  interface  having  the  specified  name. 
Installs/creates  and  locks  the  shared  communications  control  structure.  Allocates  a  communications 
channel  including  one  shared  table  for  each  of  the  data  types  specified  in  the  "datajtypes"  argument. 

Registers  the  channel  in  the  communications  control  structure. 


2.3  shmifjread .entries 


int32  shaif .read. entries (shaif ,  protocol,  exercise,  data.sink.fn,  data.sink_userdata) 
SHMIF.SHMIF  shaif; 

uint8  protocol ; 

int32  exercise; 

SHMIF_DATA_SIIK_FM  data_sink_fn; 

ADDRESS  data_sink_userdata ; 


‘shaif’  Specifies  the  shared  memory  interface  to  be  used, 
‘protocol’ 

Specifies  the  protocol  to  be  read. 

‘exercise’ 


Specifies  the  id  of  the  exercise  to  which  the  data  must  belong.  SHMIF  JEXERCISE  JD -ALL 
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can  be  used  if  data  from  all  active  exercises  is  desired.  In  general,  the  SAFSim’s  will  be 
interested  in  a  particular  exercise,  and  the  DIS  Interface  will  be  interested  in  all  active 
exercises. 

‘data.sink_fn’ 

A  function  which  takes  a  pointer  to  a  void  as  an  argument  and  which  returns  void.  For 
example:  void  sample  jdata_sink_fn(dataptr,  length,  userjdata) 

‘data. a ink_uaerdat a’ 

The  user  data  to  be  passed  back  to  the  data jinkJn  in  the  uaer.data  parameter. 

a  half  .read,  entries  checks  all  the  active  channels  belonging  to  an  process  whose  application 
type  matches  one  of  those  specified  in  appl_ types  and  whose  exercise  id  matches  the  one  specified 
in  exorcise.  For  each  of  these  channels,  shaif  .read.entries  returns  any  data  of  type  data_type 
which  has  NOT  already  been  returned  in  a  previous  call  to  shaif_read.entriess.  It  does  so  by 
making  successive  calls  to  the  data.sink_fn  function.  Returns  the  total  number  of  entries  (i.e. 
calls  to  data.sink.fn). 


2.4  shmif.w  rite  .entry 

int32  shaif .write. entry (shaif ,  protocol,  kind,  data,  length) 
SHMIF.SHMIF  shaif; 

uint8  protocol ; 

uint8  kind; 

ADDRESS  data; 

int32  length; 

‘shaif’  Specifies  the  shared  memory  interface  to  be  used. 

‘protocol’ 

Specifies  the  protocol  family  of  the  data  parameter. 

‘kind’  Specifies  the  PDU  kind  of  the  data  parameter. 

‘data’  The  data  (PDU)  to  be  written. 

‘length’  The  length  in  bytes  of  the  data  to  be  written. 

shaif  .vrite.entry  Writes  the  data  supplied  to  this  process’  channel. 


2.5  shmifjupdate 
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int32  ahaif .update (ahaif ,  data. type) 
SHMIF.SHMIF  ahaif; 

SHMIF.DATATYPE  data. type; 


‘ahaif’  Specifies  the  shared  memory  interface  to  be  used. 

‘data. type’ 

Channel  partitions  containing  this  type  of  data  will  be  updated. 


ahaif.update  Updates  the  channel  partitions  containing  the  specified  data. 


2.0  shmif.delete.nhm if 

int32  shaif.delete.shaif (ahaif) 

SHMIF.SHMIF  ahaif; 

‘ahaif’  Specifies  the  shared  memory  interface  to  be  used. 

ahaif. dolete.ahaif  deletes  the  specified  shared  memory  interface. 


2.7  shmifjdump 


int32  ahaif. duapCahaif,  string,  duap.locka) 
SHMIF.SHMIF  ahaif; 
char  *string; 

int32  duap.locka ; 


‘ahaif’  Specifies  the  shared  memory  interface  to  be  dumped, 
‘string’  Prefix  string. 


shmif.duap  prints  debugging  information  about  the  shared  memory  interface. 


2.8  shmif_protocol_kir»d_to_datatype 


SHMIF.DATATYPE  ahaif .protocol. kind. to.datatypa (protocol,  kind) 
uint8  protocol; 

uintS  kind; 
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‘protocol’ 

Specifies  the  protocol  family. 

‘entry’  Specifies  the  PDU  kind. 

shmif .protocol .kind. to.datatype  returns  the  shmif  datatype  which  corresponds  to  the  spec¬ 
ified  protocol  and  PDU  kind. 


2.0  shmif-program terror 
▼old  shmif .program. error () 

shmif .pro gram. error  prints  out  an  error  message  corresponding  to  the  last  error. 


2.10  shmif-program  -message 
void  s hmif .program. mess age () 

shmif  .program,  message  prints  out  an  error  message  corresponding  to  the  last  error. 


2.11  shmif-error -string 

char  *  shmif .error. string ( ) 

shmif -error.string  etums  an  error  string  for  the  last  error  in  the‘  libshmif. 
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1  Overview 


Libshmtbl  implements  a  simple  mechanism  for  doing  interprocess  communication  between  mul¬ 
tiple  processes  on  the  same  hardware  plc,.form.  Libshmtbl  implements  a  double-buffered  array  of 
data  entries  (i.e.  data  packets)  which  supports  simultaneous  access  to  the  table  for  reading  and 
writing.  Multiple  processes  can  read  from  the  table.  However,  the  abstraction  assumes  that  ONLY 
ONE  process  will  be  writing  to  the  table,  so  writing  is  not  controlled.  Readers  are  denied  access 
only  when  writer  updates  the  table  by  swapping  the  buffers. 
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2  Functions 


The  following  sections  describe  each  function  provided  by  libsema,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  shmtblJnit 

void  shmtbl.initO 

shmtbl.init  initializes  the  libshmtbl  library.  Currently  this  procedure  is  a  no-op. 


2.2  shmtbl^alloc_table 


SHMTBL. TABLE  shmtbl.alloc. table (key,  nentries,  entry. size,  flag,  shmid) 
ksy.t  key; 

int32  nentries ; 

int32  entry.s ize ; 

int32  flag; 

SHMTBL.ID  *shmid; 


‘key’  The  key  to  be  passed  to  shmget  to  get  the  SHMTBLJD. 

‘nentries’ 

The  number  of  entries  in  the  shared  memory  table. 

‘entry.sizs’ 

The  maximum  number  of  bytes  for  each  entry. 

‘flag’  Access  permissions  for  the  shared  memory  segment  which  the  table  occupies. 

‘shmid’  An  out  parameter  returning  the  id  of  the  shared  memory  table.  This  value  can  be  used 
as  a  parameter  to  shmtbl. install. table. 

shmtbl.alloc.table  creates  a  shared  table  using  a  shared  memory  segment  and  installs  it  in 
the  address  space  of  the  local  process.  The  shared  memory  table  has  enough  space  for  2  buffers  of 
nentries  where  each  entry  is  entry  .size  bytes  large  and  a  libsema  read/write  lock  to  control  access 
among  multiple  processes,  shmtbl.alloc.table  returns  two  values.  The  first  is  the  address  of 
the  table  in  the  local  address  space  of  the  calling  process  which  is  returned  as  the  return  value  of 
the  function.  The  second  is  a  handle  for  the  shared  memory  table  which  can  be  passed  to  remote 
processes  so  that  they  can  install  the  shared  memory  table.  This  value  is  returned  in  shmid  as  an 
out  parameter. 
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2.3  shmtbljn8tall.table 

SHMTBL.TABLE  s hmtbl. install. table(shmid) 

SHMTBL.ID  shmid; 

‘shmid’  The  id  of  the  shared  memory  table. 

shmtbl.install. table  takes  the  id  of  a  shared  memory  table  and  installs  it  in  the  local  address 
space  of  the  calling  process. 


2.4  shmtbl_uninstall  .table 

int32  shmtbl. uninstall, table  (shmtbl) 

SHMTBL.TABLE  shmtbl; 

‘shmtbl’  The  address  of  a  shared  memory  table. 

shmtbl  .uninstall  .table  takes  the  address  of  a  shared  memory  table  and  removes  it  from  the 
local  address  space  of  the  calling  process. 


2.5  shmtbljfree stable 

int32  a hmtbl.free. table (shmtbl) 

SHMTBL.TABLE  shmtbl; 

‘shmtbl’  The  address  of  a  shared  memory  table. 

s hmtbl.free. table  removes  the  specified  shared  table  from  the  local  address  space,  deletes 
deletes  it. 


2.6  shmtbl_get.version 

int32  s hmtbl.get. vers ion( shmtbl) 
SHMTBL.TABLE  shmtbl; 
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‘shmtbl’  The  address  of  a  shared  memory  table. 

shmtbl.get. vers ion  returns  the  version  of  the  shared  memory  table.  The  version  is  incre¬ 
mented  each  time  the  table  is  updated  by  shatbl.update. 


2.7  shmtbl _read  .entry 

int32  shmtbl.read.entry (shmtbl ,  entry) 

SHNTBL.TABLE  shmtbl ; 

ADDRESS  * entry ; 

‘shmtbl’  The  address  of  a  shared  memory  table. 

‘entry’  This  in  an  IN/OUT  parameter  (i.e.  a  parameter  used  by  the  calling  procedure  to 
passing  values  into  shmtbl_read_entry  and  a  parameter  used  by  shmtbl.read. entry 
pass  values  back  out  to  the  calling  procedure.  There  are  two  valid  values  which  can  be 
passed  into  shmtbl.read.entry;  SHMTBL_STARTJTERATION  and  the  address  of 
the  entry  returned  in  the  last  call  to  shmtbl.read.entry.  There  are  two  valid  values 
which  can  be  returned  by  shmtbl.read.entry;  the  address  of  the  next  entry  in  the 
table  and  SHMTBL_ABORTJTERATION. 


shmtbl.read. entry  supports  reading  through  a  shared  memory  table  an  entry  at  a  time.  It 
operates  similarly  to  the  strtok  function. 

The  first  call  to  shmtbl.read. entry  with  tentry  equal  to  SHMTBLJSTARTJTERATION  will 
lock  the  table  for  READING,  set  *entry  equal  to  the  address  of  the  first  element  in  the  table,  and 
return  the  length  of  that  element  in  bytes. 

Subsequent  calls  to  shmtbl.read.entry  with  *entry  equal  to  the  last  value  returned  iterate 
through  the  table  an  element  at  a  time.  The  final  call  to  shmtbl_read.entry  (where  *  entry 
contains  the  address  of  the  last  element  in  the  table)  unlocks  the  table  for  READING,  sets  *  entry 
equal  to  SHMTBL_ABORTJTERATION,  and  returns  0. 

The  following  is  a  code  example  of  how  ahmtbl.read.entry  should  be  used: 

ADDRESS  entry; 
int32  length; 
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entry  »  (void  *)  SHMTBL.START. ITERATION ; 

length  ■  ahntbl_read_entry( (SHKTBL. TABLE)  shaaddr,  Aentry) ; 
while  (entry  !-  SHMTBL, ABORT. ITERATION) 

{ 

proceaa.data(entry) ; 

length  ■  8hmtbl„read_entry( (SHMTBL. TABLE)  shnaddr,  Aentry) ; 

> 

> 


2.8  shmtbl.write^entry 


int32  ahatbl. write. entry (ahatbl ,  entry,  entry. size) 
SHNTBL.TABLE  ahatbl; 

ADDRESS  entry; 

int32  entry _a ize ; 

‘ahatbl’  The  address  of  a  shared  memory  table. 

‘entry’  The  address  of  the  entry  to  be  written. 

‘entry.size’ 

The  size  in  bytes  of  entry. 


ahatbl. write,  entry  writes  a  new  entry  into  the  table. 


2.9  shmtbljupdate 

int32  shatbl.update (ahatbl) 

SHNTBL.TABLE  ahatbl; 

‘ahatbl’  The  address  of  a  shared  memory  table. 

shatbl.update  locks  the  specified  shared  memory  table  for  writing,  swaps  the  read  and  write 
buffers,  increments  the  version  counter,  and  unlocks  the  table. 


2.10  shmtbl.xlump 


void  8hatbl_duap( ahatbl,  string,  duap.locka) 
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SHMTBL. TABLE  shatbl; 
char  «string; 

int32  duap. locks; 

‘shatbl’  The  address  of  a  shared  memory  table. 

‘string’  Specifies  the  procedure  name 
‘duop_ locks’ 

Specifies  whether  locks  should  be  dumped 
Prints  out  a  cryptic  one-line  summary  about  the  current  state  of  the  table. 

2.11  shmtbl_ierror 

char  *  shatbl. error () 

Returns  an  error  string  for  the  last  error  in  the  iibshmtbl. 
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1  Overview 


Libsmokedit  is  a  library  which  implements  a  smoke  mission  editor.  The  editor  will  be  used  to 
create,  delete,  change,  and  start  smoke  missions.  It  contains  four  editables.  The  first  editable, 
SMOKE-MISSION,  displays  the  name  of  the  "current"  mission,  and  has  a  button  to  push  to  create 
and  delete  smoke  missions,  and  a  menu  of  created  missions.  There  is  a  Scale  editable  (in  integer 
format)  which  specifies  the  number  of  grenades  to  launch.  The  next  editable  is  a  CHOOSE.ONE 
list  of  smoke  types,  of  which  we  only  have  one  for  the  time  being  (red  phosphorus  L8A1).  The  next 
editable  is  a  Place  editable  where  the  user  clicks  on  the  map  to  designate  the  location  at  which  to 
drop  the  smoke  grenades.  The  last  editable  is  a  TOGGLE  editable  that  says  "Launched/ Waiting” 
which  the  user  will  select  to  start  the  smoke  mission.  A  dialog  box  will  come  up  to  ensure  the  user 
knows  this  will  start  the  mission.  The  user  will  not  be  able  to  cancel  a  mission  once  it  has  started 
and  he  will  not  be  able  to  re-use  a  mission.  However,  it  will  be  easy  to  create  duplicate  missions 
because  the  next  time  he  creates  a  mission  it  will  default  to  the  parameters  of  the  previous  mission. 

One  future  enhancement  will  be  to  include  a  time  editable  to  plan  missions  in  advance.  This 
should  be  done  when  HHour  is  implemented. 

The  smoke  missions  will  be  stored  in  a  Unit  Class  PO,  with  type  diffuseMatterMediumSmoke- 
Cloud.  The  number  and  type  of  smoke  grenades  will  be  stored  in  the  munitions  array.  The  name 
of  the  mission  will  be  stored  in  the  formationTempiate  and  the  location  in  the  location  field.  When 
the  user  starts  the  mission,  the  shouldBeSimulated  field  will  be  set  to  notify  a  back  end  to  start 
simulating  the  smoke.  Although  not  completely  clean,  this  design  was  the  easiest  way  to  introduce 
smoke  into  the  PO  protocol  in  a  short  period  of  time.  Another  enhancement  would  be  to  add  a 
new  type  of  PO  PDU  for  smoke  missions. 


1.1  Examples 

Look  in  lest.c  for  a  sample  program  using  libsmokedit.  The  file  smokedit . rdr  describes  an 
editor  containing  a  smoke  mission  editor. 
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2  Functions 


The  following  sections  describe  each  function  provided  by  libsmokedit,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  smeJnit 


void  SM.inltCdnta.path,  flags) 
char  *data.path; 
uint32  flags; 


‘data.path’ 

Specifies  the  directory  path  in  which  to  look  for  the  reader  file. 

‘flags'  Specifies  the  flags  to  use  in  the  reader  .read  call  to  open  the  reader  files. 


sM.init  initializes  libsmokedit.  Call  this  before  any  other  libsmokedit  function. 


2.2  sme^create-editor 


int32 


e. create. editor (gul, sensitive,  select,  tactaap,  tcc, 

nap.erase.gc,  refresh. event,  db,  sin_addr) 
gul; 

sensitive; 
select ; 
tactaap; 

tcc; 

aap.erase.gc; 
refresh.event; 

♦db; 

•sia.addr; 


SGUI.PTR 

SISTVE.VIIDOH.PTR 

SELECT.TOOL.PTR 

TACTIUP.PTR 

COORD.TCC.FTR 

GC 

CALLBACK.EVEIT.PTR 

P0.DATABASE 

SiaulationAddress 


‘gui’  Specifies  the  SAF  GUI 
‘sensitive' 

Specifies  the  sensitivity  window 
‘select'  Specifies  the  selection  tool 
‘tactaap’  Specifies  the  tactical  map 
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‘tcc’  Specifies  the  coordinate  system 

‘■ap_erase_gc’ 

Specifies  the  GC  used  to  erase  on  the  tactical  map  (same  as  that  passed  to 

tactaap.create) 

‘refresh. event’ 

Specifies  the  event  which  fires  upon  map  refresh 
ldb’  Specifies  the  PO  database. 

‘sia_aadr’ 

Specifies  the  simulation  address  of  the  local  workstation. 


sae.create.editor  creates  a  smoke  mission  editor  and  makes  it  available  via  the  select  editor. 
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1  O  verview 


LibStatMon  provides  a  user  interface  for  monitoring  unit  status.  It  provides  a  facility  whereby 
tasks  can  register  functions  to  generate  user-readable  status  messages  based  upon  internal  task 
state  (see  Section  3.2  [statmon'register],  page  7). 

At  program  startup,  another  editor  (in  ModSAF,  the  Unit  Operations  editor)  initializes  libStat- 
Mon.  This  does  little  more  than  set  the  stage  for  more  operations  at  run  time.  Also  at  startup, 
each  task  which  has  state  which  is  shared  (via  the  PO  database)  can  register  a  function  which  is 
capable  of  translating  this  binary  representation  to  a  human-readable  string. 

Later,  when  the  program  is  up  and  running,  the  controlling  editor  passes  libStatMon  a  unit  ID 
for  monitoring.  LibStatMon  installs  callbacks  for  various  libPO  events,  so  that  it  can  update  the 
status  display  whenever  the  tasks  change. 

The  status  monitor  creates  a  Motif  RowColumn  widget  for  each  opaque  task  frame  in  the 
monitored  unit’s  stack,  and  one  for  its  background  frame.  Each  task  in  the  task  frame  (for  which 
a  status  function  has  been  registered)  is  given  a  Widget  in  this  RowColumn.  In  the  topmost 
stack  frame  and  the  background  frame,  these  are  toggle  buttons,  in  other  frames  they  are  labels. 
Status  messages  are  generated  and  displayed  for  running  tasks  for  which  the  toggle  button  has  been 
selected. 


Although  the  toggle  buttons  appear  to  be  per-task,  they  are  actually  selecting  status  on  a  per- 
SAF- Model  basis.  That  is,  once  the  Vehicle- Follow- Route  task  has  been  selected  for  a  unit;  that 
task  will  default  to  being  selected  whenever  it  is  active  in  a  task  frame  for  a  selected  unit  (until  the 
user  explicitly  chooses  not  to  see  that  status  message).  This  information  is  saved  on  a  per-status- 
monitor  basis,  so  that  if  more  than  one  status  monitor  were  create  in  a  single  ModSAF  system, 
each  would  act  independently. 

As  a  mission  progresses,  the  number  of  tasks  and  task  frames  which  a  unit  uses  changes.  How¬ 
ever,  libStatMon  never  destroys  a  widget.  Instead,  it  manages  and  unman  ages  widgets  as  they  are 
needed,  and  changes  their  labels  to  reflect  specific  task  names.  This  should  reduce  fragmentation 
of  X  server  memory  (a  common  problem  when  the  display  is  not  stable). 
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2  U  sage 


The  software  library  ‘libstataon.a’  should  be  built  and  installed  in  the  directory 
‘/coamon/lib/’.  You  will  also  need  the  header  file  ‘libstataon.h’  which  should  be  installed  in  the 
directory  ‘/cossson/ include/lib  inc/’.  If  these  files  are  not  installed,  you  need  to  do  a  ‘asks’  in 
the  libstatmon  source  directory.  If  these  files  are  already  built,  you  can  skip  the  section  on  building 
libstatmon. 


2.1  Building  Libstatmon 

The  libstatmon  source  files  are  found  in  the  directory  ‘/coaaon/libsrc/libstataon’.  ‘RCS’ 
format  versions  of  the  files  can  be  found  in  ‘/nf  s/coaaon.src/libsrc/libstataon’. 

If  the  directory  ‘coaaon/libsrc/libatataon’  does  not  exist  on  your  machine,  you  should  use 
the  ‘genbuild’  command  to  update  the  common  directory  hierarchy. 

To  build  and  install  the  library,  do  the  following: 

•  cd  coaaon/libsrc/libstataon 

•  co  RCS/*,v 

•  aaka  install 

This  should  compile  the  library  'libstataon.a’  and  install  it  and  the  header  file  ‘libstataon.h’ 
in  the  standard  directories.  If  any  errors  occur  during  compilation,  you  may  need  to  adjust  the 
source  code  or  ‘Hakef  ile’  for  the  platform  on  which  you  are  compiling,  libstatmon  should  compile 
without  errors  on  the  following  platforms: 

•  Mips 


2.2  Linking  with  Libstatmon 

Libstatmon  can  be  linked  into  an  application  program  with  the  following  link  time  flags:  ‘Id 
[source  ,o  files]  -L/coaaon/lib  >18181800  [other  ModSAF  libraries]’.  If  your  compiler  does 
not  support  ‘-L’  syntax,  you  can  use  the  archive  explicitly:  ‘Id  [source  .o  files]  /comson/lib/libstataon. 


Libstatmon  depends  on  libpo,  Ubcoordinates,  and  libsched. 
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2.3  Examples 

The  following  code  segments  appeared  in  an  early  version  of  the  vehicle-level  target  assessment 
task.  The  function  status  translates  the  contents  of  the  task  to  a  user-readable  format.  Note 
the  use  of  edt.format  to  format  the  vehicle  ID  in  a  standard  fashion,  adt .format  should  be 
used  whenever  possible,  to  provide  a  consistent  interface  (see  section  ‘edt -format’  in  LibEditor 
Programmer’s  Manual). 


•include  " libvass. local .h" 

•include  <libstat»on.h> 

•include  <libeditor.h> 

•include  <stdext.b> 

•include  <p.saf models. h> 

static  void  statusCtask,  state,  task.id,  context,  description) 

TaskClass  *task; 

TaskStateClass  estate; 

ObjectID  * task .id; 

STATMOI. COITEZT  econtezt; 
char  descript ion  □ ; 

{ 

V ASSESS .STATE  estatevars  •  (VASSESS .STATE  *)atate->data; 
char  ed; 
int32  i; 

switch  (statevars->state) 

i 

default : 

sprintf (description,  "lot  running"); 
break; 

case  suspended: 

sprintf (description,  "Suspended") ; 
break; 

case  looking: 

sprintf (descript ion,  "Looking  for  a  target"); 

break; 

case  reevaluating: 

edt„f ormat  (context ->gui ,  description , 

"Best  target  is  *v,  using  IS  (permission  fS)", 
ftst  at  wars ->recomMndat  ion.  target , 
st  atevars  -  >reco— andat  ion .  weapon , 
vass.permission_string(shared-> 

state. recoMandation. permission)) ; 

break; 

> 

> 


void  vass.initO 
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uint32  bef ore. tasks [1] ; 

before. tasks [0]  ■  SM.VSpotter; 

▼assess. init.f saCSM.VAssess , 

HULL,  /*  predicate  */ 

i,  bef ore. tasks ,  /*  before  */ 

0,  HULL  /*  after  */ 

); 

▼ass.init.access ( ) ; 

▼ass.init.paraasO ; 

stat»on_register(SM_VAssess,  "Target  Assessaent" ,  status); 

> 
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3  Functions 

The  fallowing  section*  describe  each  function  provided  by  libstatmon,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 

3.1  statmonJnit 

void  stataon.init() 

stataon.init  initializes  libstatmon.  Call  this  before  any  other  libstatmon  functions. 


3.2  statmon -register 


void  statnan.register(saf jaodel,  naan,  status) 
uint32  saf .nodal ; 

char  *nane; 

STATMOI.STATUS.FUICTIOI  status; 


‘safjBodel’ 

Specifies  the  SAF  model  implemented  by  the  task  (from  ‘p.safnodels  .h’) 

‘nane’  Specifies  the  user-readable  name  of  the  task 

'status’  Specifies  the  function  to  translate  task  state  variables  to  a  descriptive  message 

statnon.register  registers  a  status  function  with  libstatmon.  This  should  be  called  by  any 
task  which  has  state  which  might  be  meaningful  to  the  user.  The  name  is  copied  into  allocated 
memory. 


The  status  function  should  be  declared  as  follows: 


static  void  status (task,  stats,  task.id,  context,  description) 
TaskClass  *task; 

TaskStateClass  estate; 

Object 10  etask„id; 

STATMOI.COITEZT  econtext, 
char  description  □ ; 
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To  fyiH****  useful  messages,  the  Object  ID  of  the  task,  the  PO  database,  and  the  GUI  (which 
can  be  used  by  libEditor  to  do  type  conversions)  are  all  passed  as  well  (see  section  ‘edt .format’  in 
LibEditor  Programmer’s  Manual).  The  resulting  string  should  be  returned  in  description  (a  10K 
character  buffer).  The  string  should  not  start  with  the  task  name  (that  is  done  automatically),  nor 
should  it  end  with  a  \n.  It  should  be  NULL  terminated. 

LibStatMon  translates  embedded  newlines  into  vertical  bars  ( I ),  for  readability.  However,  you 
can  force  a  newline  in  the  output  by  using  \\n  within  your  string.  For  example: 


edt.f orant (context ->gui ,  descript ion , 

"Best  target  is  fvWnUsing  •S", 
tstatevars->reco— sedation .  target , 
st  atevars- >recoraandttion .  weapon) ; 


The  context  structure  is  declared  as  follows: 


typedef  struct  stataan_context 

i 

ADDRESS  gui: 

PO.DATABASE  *db; 
COORD.TCC.PTR  tcc; 

>  STATMOI.COITEXT ; 


In  the  future,  this  structure  could  expand  to  include  other  context  information  which  may  be 
needed  by  tasks  to  generate  useful  messages. 


3.3  stntm  on -create 


STATMOI.GUI.Pni  stetson. create(context ,  controls.rc ,  text.disply, 

aonaal.resime.btn,  react ion.resusw.btn, 
caacel.btn,  react ion.btn) 

STATHOI.COWTEXT  * context ; 

Widget  controls.rc; 

Widget  text.disply; 

Widget  noranl.resime.btn; 

Widget  react ion. resune.btn; 

Widget  caacel.btn; 

Widget  resctioa.btn; 


’context’  Specifies  the  system  run  time  context 
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‘controls.rc’ 

Specifies  the  Motif  Row  Column  widget  in  which  the  control*  we  to  be  placed 
‘text.disply’ 

Specifies  the  Motif  Text  widget  in  which  status  is  to  be  displayed 

‘nonal.reauM.btn’ 

‘react  ion.resuae.btn’ 

Specify  buttons  which  are  to  be  sensitive  when  the  unit  is  executing  a  resumable  task 
frame.  Only  will  be  managed,  depeding  upon  whether  the  unit  is  executing  a  reaction. 

‘cancel.btn’ 

Specifies  a  button  which  is  to  be  sensitive  when  the  unit  is  executing  a  cancelable 
override 
‘cancel.btn’ 

Specifies  a  button  which  is  to  be  sensitive  when  the  unit  is  executing  a  reaction 

stataon. create  creates  a  status  monitor  GUI.  The  reauae.btn,  if  non-NULL,  will  be  made 
sensitive  whenever  the  currently  monitored  unit  has  a  resumable  mission  (a  task  frame  stack  with 
depth  >  1).  The  cancel.btn,  if  non-NULL,  will  be  made  sensitive  whenever  the  currently  monitored 
unit  has  a  cancelable  override  (a  n on-preprogrammed  transparent  frame). 


3.4  statmon^enable 

void  stataon. enable (stataon,  unit,  id) 

STATMOI.GUI.PTR  stataon; 

Object ID  eunit.id; 

‘stataon’  Specifies  the  status  monitor 
‘unit. id’  Specifies  the  unit  to  monitor 

stataon.enable  enables  the  status  monitor,  and  assigns  the  unit  to  be  monitored. 


3.5  statmomdisable 

void  stataon.disable(stataon) 
STATMOI.GUI.PTR  stataon; 

‘stataon’  Specifies  the  status  monitor 
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1  O  verview 


Libstealth  provides  libentity-lixe  functionality  for  interacting  with  stealth  views.  In  this  model, 
stealths  (both  remote  stealths,  and  local  stealth- preview  views)  are  placed  in  the  vehicle  table,  and 
given  a  VTAB.RSNOTE.STEALTH  or  VTAB.LOCAL.STEALTH  vehicle  type.  Applications  can  interact 
with  all  stealths  the  same  way,  regardless  of  their  type.  In  the  future,  this  library  may  be  extended 
to  support  different  network  stealth  protocols  as  well. 

The  stealth  (also  referred  to  as  the  Flying  Carpet)  presents  a  three-dimensional  view  of  the 
simulated  battlefield.  Data  packets  projected  onto  the  appropriate  network  exercise  allow  the 
objects  they  represent  to  be  viewed  on  the  stealth.  Much  of  the  libstealth  code  deals  with  stealth 
protocol  packets. 

The  haphazard  nature  of  the  current  stealth  protocol  (as  defined  in 
fileCcommon/src/protocol/p  jtlth.drn})  limits  the  ability  of  this  library  to  provide  a  simple  inter¬ 
face.  Commands  to  teleport,  attach,  and  set  the  mode  (tether,  orbit,  free  fly,  etc)  of  the  stealth 
are  all  separate,  despite  their  dose  relationships.  Furthermore  there  is  very  little  feedback  from  the 
stealth  about  its  current  operational  status.  Future  stealth  work  should  correct  these  problems,  at 
which  time  the  interface  to  this  library  will  probably  be  improved. 


1.1  Attachment  Mode* 

Currently  there  are  five  ModSAF  stealth  attachment  modes: 

tether  The  stealth  is  attached  to  a  vehide  at  a  certain  distance  and  bearing.  The  stealth 
moves  with  the  vehide,  changing  its  speed  and  direction  automatically  as  the  vehide 
does.  The  spaceball  movements  allow  the  stealth  to  free  fiy  relative  to  the  vehide,  not 
the  terrain. 

compass  The  stealth  is  attached  to  a  vehide  at  a  certain  distance  and  bearing.  The  stealth 
moves  with  the  vehicle,  changing  its  speed  automatically  as  the  vehide  does.  However, 
the  stealth  will  not  change  its  direction.  It  remains  faring  the  same  direction  even  if 
the  vehide  turns.  The  spaceball  movements  allow  the  stealth  to  free  fiy  around  the 
vehide. 

orbit  The  stealth  is  attached  to  a  vehide  at  its  center  of  mass.  The  stealth  always  moves  with 
the  vehide.  The  spaceball  movements  allow  the  stealth  to  spherically  travel  around 
the  vehide  which  remains  in  the  center. 


2 


LibStealth  Programmer’s  Guide 


mimic  The  stealth  becomes  imbedded  with  the  target  vehicle,  inheriting  all  components  of 
velocity  and  orientation.  The  spaceball  movements  allow  the  stealth  to  slew  its  view 
up  and  down  and  to  yaw  around  the  Z  axis  of  the  target  vehicle  to  facilitate  viewing 
in  all  possible  directions. 

free  fly  The  stealth  moves  with  the  dynamics  of  an  airplane.  The  stealth  is  not  attached  to 
any  vehicle  or  terrain  location.  The  spaceball  movements  allow  the  stealth  to  free  fly 
around  the  terrain. 


1.2  Algorithms 

When  ModSAF  receives  a  stealth  appearance  packet,  the  last  appearance  time  for  that  stealth 
is  updated  so  that  the  stealth’s  time  out  clock  can  be  reset.  If  enough  time  elapses  (10  seconds) 
without  a  new  stealth  appearance  packet,  the  stealth  will  be  removed  from  ModSAF’s  vehicle 
table.  ModSAF  extracts  the  stealth’s  position  and  direction  from  the  stealth  appearance  packet. 
The  ModSAF  Station  needs  this  libstealth  user  data  when  drawing  the  PVD  arrow  icon  which 
indicates  the  current  location  and  azimuth  of  the  stealth. 

When  a  stealth  attached  packet  is  received,  libstealth  examines  the  vehicle  table  for  vehicles 
with  type,  VTAB_REMOTE_STEALTH,  to  locate  a  stealth  with  the  same  simulation  address  as  the 
sender.  This  needs  to  be  done  since  the  vehicle  ID  of  the  stealth  is  not  part  of  the  stealth  attached 
packet.  If  an  appropriate  vehideid  can  not  be  found,  libstealth  ignores  the  packet.  Otherwise,  the 
libstealth  user  data  is  marked  with  the  vehide  ID  that  the  packet  identifies  as  the  stealth’s  current 
attachment  vehide.  The  stealth  attached  packet  is  sent  by  the  stealth  whenever  the  stealth  becomes 
attached  to  a  new  vehide  (no  matter  whether  this  was  caused  by  a  packet  sent  from  ModSAF  or 
a  stealth  user's  input.  It  is  also  sent  by  the  stealth  whenever  it  ceases  to  be  attached  to  a  vehicle, 
for  whatever  reason  (  a  new  attach  packet  from  ModSAF,  entering  independent  velodty  mode, 
attached  vehide  vanishing,  etc).  In  this  case,  the  ’detached’  field  is  set  to  TRUE. 

A  ModSAF  user  can  request  a  stealth  teleport.  Since  the  local  preview  views  do  not  support 
the  stealth  protocol,  the  method  used  for  teleport  differs  between  LOCAL  and  REMOTE  stealths. 
For  local  previews,  teleports  are  performed  by  invoking  a  callback  function  provided  at  program 
initialization;  this  callback  subsequently  invokes  a  function  in  libpreview  to  perform  the  teleport. 
For  remote  stealths,  a  Teleport  PDU  is  sent  via  libpktvalve  to  the  stealth  to  cause  it  to  move  to  a 
new  location  and/or  assume  a  new  orientation. 

A  ModSAF  user  can  request  a  stealth  attachment  to  a  vehicle.  Since  the  local  preview  views  do 
not  support  the  stealth  protocol,  the  method  used  for  attaching  differs  between  LOCAL  and  REMOTE 
stealths.  For  local  previews,  attaches  are  performed  by  invoking  a  callback  function  provided  at 
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program  initialisation;  this  callback  subsequently  invokes  a  function  in  libpreview  to  perform  the 
attachment.  For  remote  stealths,  a  Visibility  PDXJ  is  sent  via  libpktvalve  to  the  stealth  to  send 
it  the  exercise  id.  Then  a  Teleport  PDU  is  sent  using  the  position  of  the  targeted  retrieved  from 
libentity  as  the  teleport  location.  Then  an  Attach  PDU  is  sent  to  cause  the  stealth  to  become 
attached  to  the  indicated  vehicle. 

A  ModSAF  user  can  request  a  change  in  stealth  attachment  mode.  Since  the  local  preview  views 
do  not  support  the  stealth  protocol,  the  method  used  for  mode  change  differs  between  LOCAL  and 
REMOTE  stealths.  For  local  previews,  mode  changes  are  performed  by  invoking  a  callback  function 
provided  at  program  initialization;  this  callback  subsequently  invokes  a  function  in  libpreview  to 
perform  the  mode  change.  For  remote  stealths,  a  Metamorphose  PDU  is  sent  via  libpktvalve  to 
the  stealth  to  cause  it  to  assume  a  particular  attach  mode  while  attached  to  a  vehicle. 
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2  Functions 


The  following  sections  describe  each  function  provided  by  libstealth,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  stealthJnit 


void  steal th_init (valve,  protocol) 
PV.VALVE.PTR  valve; 
int32  protocol; 


'valve*  Specifies  the  packet  value 
'protocol* 

Specifies  the  protocol  to  use  (SIMNET,  DIS  1.0,  DIS  2.0,  etc.) 
stealth.init  initializes  libstealth.  Call  this  before  calling  any  other  libstealth  functions. 


2.2  stealth  -class-in  it 

void  stealth.class.init (parent. class) 

CLASS. PTR  parent. class; 

'parent. class’ 

Identifies  the  parent  class  for  per-itealth  information  (probably  safobj  .class). 

stealth.class.init  creates  a  handle  for  attaching  stealth  class  information  to  vehicles.  The 
parent.dass  is  one  created  with  class.declare.dass. 


2.3  stealth  .xreate 


void  stealth.create(vehide.id,  deactivate.fcn) 
int32  vehicle. id; 

void  (edeactivate_f cn) (/*  int32  vehicle. id  a/); 
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‘vehicle.id’ 

Specifies  the  vehicle  ID 

‘deactivate.fcn’ 

Specifies  the  function  to  call  if  the  stealth  deactivates 

stealth. create  creates  the  stealth  class  information  for  a  stealth  and  attaches  it  to  the  stealth’s 
libdass  user  data. 


2.4  stealth  .destroy 

void  at ealth. destroy (vehicle, id) 
int32  vehicle. id; 

‘vehicle,  id’ 

Specifies  the  vehicle  ID 

steal th_destroy  frees  the  stealth  class  information  for  a  stealth. 


2.5  stealthjtick 

void  steal th.tick(vehide.id) 
int32  vehicle. id; 

‘vehicle. id’ 

Specifies  the  vehicle  ID 

stealth.tick  checks  the  stealth  for  network  time  out. 


2.0  stealth  .appearance  .received 


void  st ealth. appearance .received (vehicle. id,  packet) 
int32  vehicle. id ; 

PV.PACKET  vpacket ; 
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‘vehicle.id’ 

Specifies  the  vehicle  ID 

‘packet'  Specifies  the  packet  (from  libpktvalve) 

stealth. appear ance.receired  informs  the  stealth  of  a  received  appearance  packet. 


2.7  stealth_set-preview 


void  stealth.net .preview (vehicle. id,  prsvisv.nuabsr,  previev.user.dat a , 

teleport,  attach) 

lnt32  vehicle. id; 

int32  previev.nuaber ; 

ADDRESS  previev.user.dat a; 

void  (*teleport) (/•  user.data,  position[3],  angle  •/); 
void  (*attach)(/e  user.data,  target.id,  node  */); 


‘vehicle.id’ 

Specifies  the  vehicle  ID 

‘previev.nuaber’ 

Specifies  the  serial  number  of  the  preview 
‘previev.user.data’ 

Specifies  user  data  which  uniquely  identifies  the  preview 

‘teleport’ 

Specifies  a  function  to  call  to  teleport  the  preview 

‘attach’  Specifies  a  function  to  call  to  attach  a  preview  (the  node  is  one  of  the  dynamics  modes 
from  ‘p.stlth.h’). 

steal th.set.previev  sets  parameters  for  local  stealth  view. 


2.8  stealth-update_preview 


void  steal th_update_previes(vehicle.id,  position,  direction,  attachment) 
int32  vehicle. id; 

float64  posit ion [3] ; 
floated  direction [3] ; 
int32  attachaent; 
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‘vehide.id’ 

Specifies  the  vehicle  ID 

‘position’ 

Specifies  the  preview’s  position 

‘direction’ 

Specifies  the  preview's  direction 
‘attachMat' 

Specifies  the  vehicle  to  which  the  preview  is  currently  attached  (or  0) 


steal th.update.previev  updates  changing  data  regarding  a  local  stealth  view. 


2.9  stealth.get_posttion 


void  stealth^et  .posit  ion  (vehicle,  id,  position) 
JLnt32  vehicle,  id; 
floated  position  [3 j ; 


‘vehicle. id’ 

Specifies  the  vehicle  ID 

*poBitian’ 

Returns  the  position 


steal  th.get_positian  gets  the  position  of  a  stealth  vehicle. 


2.10  stealth.get.jdirection 

floated  steal th^et.direction(vehicle.id) 
int32  vehicle. id; 


‘vehicle. id’ 

Specifies  the  vehicle  ID 


stealth_get. direct  ion  gets  the  direction  of  a  stealth  vehicle. 
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2.11  stealth_get  -attachment 

int32  steal th.get.attachaent (vehicle.id) 
lnt32  vehicle. id; 

’vehicle.id’ 

Specifies  the  vehicle  ID 

stealth.get.attachaent  gets  the  current  attachment  of  a  stealth  vehicle  (not  guaranteed  to 
be  correct).  Returns  0  if  unknown  or  not  attached. 


2.12  stealth  .attach 

void  stealth.attachCvehicle.id,  target.id) 
int32  vehicle. id; 
int32  target.id; 

’vehicle.id’ 

Specifies  the  vehicle  ID 

’target.id’ 

Specifies  the  target  of  the  attachment 
steal th.attach  attaches  a  stealth  to  another  vehicle. 


2.13  stealth  .set  anode 

void  stealth.setjaode (vehicle. id,  node) 
int32  vehicle.id; 
int32  node; 

’vehicle.id’ 

Specifies  the  vehicle  ID 

’aode’  Specifies  the  mode 

steal th.set.aode  sets  the  mode  of  the  stealth  to  one  of  the  choices  for  the 
MetaaorphoseVariant  in  ‘p.stlth.h’. 
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2.14  stealth-teleport 


▼old  stealth.teleport(vahide.id,  location,  aziauth) 
int32  vehicle. id; 
float 64  location [3] ; 
float64  aziauth; 


'tehide.id' 

Specifies  the  vehicle  ID 

'location' 

Specifies  the  location 
‘aziauth’  Specifies  the  azimuth 

steal th.teleport  teleports  a  stealth  to  a  new  location  Sc  azimuth. 


2.15  stealth-get-preview  .number 

int32  stealth.get.previev_nuaber( vehicle. id) 
int32  vehicle. id; 

‘vehicle. id’ 

Specifies  the  vehicle  ID 

steal th_get.previev_nuaber  gets  the  preview  number  associated  with  a  local  stealth  view 
(returns  0  for  remote  stealths). 


2.16  stealth  .get-color 

int32  steal th_get_color(vehide_id) 
int32  vehicle. id; 

‘vehicle. id' 

Specifies  the  vehicle  ID 

steal th_get. color  gets  the  force  ID  associated  with  a  stealth.  Each  stealth  is  assigned  a 
different  force  ID  when  it  is  received  to  allow  visual  distinction  of  different  stealth  views  on  the 
PVD. 
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1  O  verview 


Libsupplies  provides  a  simple  facility  for  sapply  management  within  a  vehicle  simulation.  The 
vehicle  sub-class  maintains  a  list  of  munitions,  and  the  amounts  of  those  munitions.  A  negative 
amount  signifies  that  the  amount  is  never  decremented.  A  single  type  of  munition  may  be  stored 
in  more  than  one  place.  Functions  are  provided  to  check  the  levels  of  a  given  supply,  to  set  the 
supply  levels  explicitly,  or  to  decrement  the  amount  of  a  supply. 

The  initial  levels  are  specified  in  the  vehicle’s  configuration,  as  follows: 

(supplies  (<*unition  integer*  <quantity  float*  < auto .resupply  charptr*) 
(<aunition  integer*  <quantity  float*  < auto. resupply  charptr*) 

•  •  e 

) 

Note  that  the  first  appearance  of  a  munition  goes  in  store  0,  the  second  in  store  1,  and  so  on. 
The  meaning  of  store  numbering  depends  upon  the  components.  The  auto_resupply  variable  can 
left  out  or  set  as  unlimited. 
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2  Usage 


The  software  library  ‘libsupplies.a’  should  be  built  and  installed  in  the  directory 
7co— on/lib/’  You  will  also  need  the  header  file  ‘libsupplies.h’  which  should  be  installed  in 
the  directory  ‘/coemon/include/libinc/’.  If  these  files  are  not  installed,  you  need  to  do  a  ‘sake’ 
in  the  libsupplies  source  directory.  If  these  files  are  already  built,  you  can  skip  the  section  on 
building  libsupplies. 


2.1  Building  Libsupplies 

The  libsupplies  source  files  are  found  in  the  directory  '/coanon/libsrc/libsupplies’.  ‘RCS’ 
format  versions  of  the  files  can  be  found  in  ‘/nfs/ccemon.src/libsrc/llbsupplies’. 

If  the  directory  ‘coemon/libsrc/libaupplles’  does  not  exist  on  your  machine,  you  should  use 
the  ‘genbulld’  command  to  update  the  common  directory  hierarchy. 

To  build  and  install  the  library,  do  the  following: 

•  cd  rnwin/libsrc/libsuppliea 

•  co  RCS/e.v 

•  sake  install 

This  should  compile  the  library  'libsupplies.a’  and  install  it  and  the  header  file 
'libsupplies  .h’  in  the  standard  directories.  If  any  errors  occur  during  compilation,  you  may  need 
to  adjust  the  source  code  or  'Makefile’  for  the  platform  on  which  you  are  compiling,  libsupplies 
should  compile  without  errors  on  the  following  platforms: 

•  Mips 

•  SGI  Indigo 

•  Sun  Sparc 


2.2  Linking  with  Libsupplies 

Libsupplies  can  be  linked  into  an  application  program  with  the  following  link  time  flags:  'Id 
[source  .o  files]  -L/coaaon/lib  -lsupplies  -lvtab  -ldass  -lrdrconst  -lpamgr 


4 


LibSupplies  Programmer's  Guide 


-lreader  -11’.  If  your  compiler  does  not  support  ‘-L’  syntax,  you  can  use  the  archive  explicitly: 
‘Id  [source  .o  files]  /cn— nn/lib/libsupplies . a’. 

Libsupplies  depends  on  libdass,  libvtab,  libparmgr,  and  librdrconst. 


2.3  Examples 


To  check  if  there  is  fuel,  after  running  out  of  gas: 


if  (supp.get.aaount (vehicle. id ,  aunit ion. Fuel,  0)  !•  0.0) 

track ed->stete  ■  TRACKED.STATE.HEALTHY ; 

capnt. available (vehicle. id,  SH.TrackedHull,  TRUE) ; 


To  use  some  fuel: 


if  (supp_decreaent( vehicle. id,  aunit ion. Fuel,  0, 

dt  *  speed  /  tracked->paraM->fuel_usage_apl)  ■■0.0) 

tracked->state  ■  TRACKED. STATE.I0GAS ; 

capnt. available (vehicle. id,  SM.TrackedHull ,  FALSE); 
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3  Functions 


The  following  sections  describe  each  function  provided  by  libsupplies,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


3.1  suppJnit 

void  supp.initO 

•upp.lnit  initializes  libsupplies.  Call  this  before  calling  any  other  libsupplies  functions. 


3.2  suppress Jnit 

▼old  supp.class.initCparent.dass) 

CLASS.PTR  parent. class; 

‘parent.dass’ 

Class  of  the  parent  (declared  with  class.declare.class) 

supp.class.init  creates  a  handle  for  attaching  supplies  class  information  to  vehicles.  The 
parent.dass  is  one  created  with  class jdedarejdaas. 


3.3  supp_create 

void  supp.create (vehicle. id,  paras) 

int32  vehicle. id; 

SUPPLXES.PUUMETRIC.Dm  *paras; 

'vehicle. id’ 

Specifies  the  vehicle  ID 

‘paras’  Specifies  the  initial  parameter  values 

supp.create  creates  the  supplies  class  information  for  a  vehicle  and  attaches  it  to  the  vehicle’s 
libdass  user  data. 
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3.4  supp_destroy 

void  supp.destroy (vehicle. id) 
int32  vehicle. id; 

‘vehicle.id’ 

Specifies  the  vehicle  ID 


supp.destroy  frees  the  supplies  class  information  for  a  vehicle. 


3.5  supp-set-quantities 


void  supp.set.quant it ies (vehicle. id,  n.quantities,  quantities) 
int32  vehicle. id; 

int32  n.quaat it ies ; 

KunitionQuantity  ^quantities; 


‘vehicle. id’ 

Specifies  the  vehicle  ID 

^.quantities’ 

Specifies  the  number  of  quantities  available 
‘quantities* 

Specifies  a  list  of  munition  quantities 


supp.set.quantities  sets  the  quantities  of  each  supply  to  that  specified  in  the  array  of 
KunitionQuantity.  The  order  of  munitions  is  significant  (they  are  assigned  to  stores  in  order). 


3.6  supp^etjquantities 


void  supp_get_quant it ies (vehicle. id,  n.quantities,  quantities) 
int32  vehicle. id; 

int32  n.quantities; 

KunitionQuantity  •quantities; 


‘vahicle.id’ 

Specifies  the  vehicle  ID 
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’ll.  quantities’ 

Specifies  the  number  of  quantities  desired 
‘quantities’ 

Returns  a  list  of  munition  quantities 

supp~get .quantities  gets  the  quantities  of  each  supply.  n_ quantities  identifies  the  number 
of  quantities  expected  (any  unused  spaces  will  be  filled  with  zeros). 


3.7  supp-set^all-full 


▼oid  supp_set.all.full (vehicle. id) 
int32  vehicle. id; 


‘vehide.id’ 

Specifies  the  vehicle  ID 

s19p.set_all.full  restores  every  quantity  to  the  initial  level  specified  in  the  parametric  data. 


3.8  supp-set.percent 


void  supp.set .percent (vehicle. id ,  Monition,  store,  percent) 
int32  vehide.id; 
uint32  ssmition; 
int32  store; 
float64  percent; 


‘vehide.id’ 

Specifies  the  vehicle  ID 

‘Munition’ 

Specifies  the  munition  type 
‘store’  Specifies  the  store  number 
*percent’  Specifies  the  percentage  (100.0  ==  full) 


supp.set.percent  sets  the  specified  Monition  (in  the  specified  store)  to  the  specified  percent 
of  the  amount  set  in  the  parametric  data. 
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3.9  lupp^etamount 


floated  supp_get_a»ount (vehide.id,  Munition,  store) 
int32  vehide.id; 
uint32  Munition; 
int32  store; 

'vehide.id' 

Specifies  the  vehicle  ID 

'Munition' 

Specifies  the  munition  type 
'store'  Specifies  the  store  number 

supp_get_au0unt  returns  the  amount  of  the  specified  Munition  (in  the  specified  store)  which 
is  currently  available.  If  the  amount  is  negative,  which  signifies  automatic  resupply  is  set,  the 
absolute  value  of  the  amount  is  returned. 


3.10  supp^etjnnxjimount 


floated  supp_get _Max_anount (vehicle. id ,  Munition,  store) 
intS2  vehicle,  id; 
uint32  Munition; 
int32  store; 


'vehide.id' 

Specifies  the  vehicle  ID 

'Munition' 

Specifies  the  munition  type 
'store'  Specifies  the  store  number 

supp_get_anount  returns  the  amount  of  the  specified  munition  (in  the  specified  store)  which 
would  be  available  if  the  vehicle  were  fully  loaded. 


3.11  supp^decrement 


floated  supp.decrenent (vehicle. id.  Munition,  store,  quantity) 
int32  vehide.id; 
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uint32  Munition; 
int32  store ; 
float 64  quantity; 

‘vehide.id* 

Specifies  the  vehicle  ID 

‘Munition’ 

Specifies  the  munition  type 
‘•tore*  Specifies  the  store  number 
‘quantity* 

Specifies  the  amount  to  use 

aupp.decreaant  decrements  the  specified  Munition  (in  the  specified  atore)  by  the  specified 
amount  and  returns  the  amount  remaining.  This  happens  only  if  the  autojesupply  variable  is  NOT 
set.  If  the  amount  is  negative,  meaning  the  auto-resupply  variable  is  set  for  the  specified  Munition, 
supp. decrement  returns  the  negative  of  the  amount. 


3.12  supp_set_qty 

int32  supp_set.qty( vehicle .id,  Munition,  atore,  quantity) 
int32  vehicle. id; 

uint32  Munition; 
int32  atore; 
float64  quantity; 

‘vehide.id’ 

Specifies  the  vehicle  ID 

‘Munition* 

Specifies  the  munition  type 
‘atore’  Specifies  the  store  number 
‘quantity’ 

Specifies  the  amount  to  use 

aupp.aet.qty  looks  for  the  specified  Munition  (in  the  specified  atore)  and  sets  it  to  the  speci¬ 
fied  quantity.  Negative  quantities  are  allowed,  and  will  signify  an  unlimited  supply  of  the  specified 
amount.  The  following  error  values  can  be  returned; 


‘sopp.set.veh.it’ 
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the  vehicle  was  not  found. 
‘S0PP.SET_STR.IF’ 

the  specified  munition/store  was  not  found. 
‘SUPP.SET.D0iE’ 

The  specified  munition/store  was  set. 
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1  Overview 


LibTactM&p  provide*  a  flexible  2D  map  drawing  facility.  An  application  can  create  an  arbitrary 
number  of  maps,  and  specify  terrain  and  other  features  for  display.  Some  terrain  features  and  all 
other  features  can  also  be  made  sensitive  (and  optionally  hot,  and  dragable)  using  libSensitive.  The 
map  drawing  routines  are  optimized  for  speed,  and  map  redraw  can  span  multiple  ticks  to  facilitate 
use  in  conjunction  with  real  time  simulation  (within  a  single  process). 

The  following  are  the  terrain  features  which  an  application  can  display: 

TACTHAP.HYPSO 

Hypsometric  background 

TACTIUP.HAIEll 

Rivers  and  lakes  (includes  any  polygon  defined  by  its  soil  type,  including  no-go  and 
slow-go  terrain). 

TACTMAP.RO ADS 

Roads 

TACTMAP.TREES 

Trees,  tree  lines,  and  tree  canopies 
TACTMAP.BUILDIIGS 

Buildings,  power  pilons,  other  structures 

TACTMAP.PIPELIIES 

Pipelines 

TACTHAP.POLITZCAL 

Political  Boundaries 

TACTMAP.RAILROADS 

Railroads 

TACTMAP.POMERLIMES 

Powerlines 

TACTMAP.COITOORS 

Contour  lines 

TACTMAP.TOHVS 

Towns 

TACTMAP.GRIDS 

Grid  lines 

In  addition,  an  application  can  create  an  arbitrary  number  of  the  following  objects: 


■ 
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TACTNAP.LIlEiR 

Linear  objects  (routes,  minefields,  etc.);  the  application  specifies  the  vertices  (in  me¬ 
ters),  line  style,  width,  and  GC. 

TACTMAP.PIXKAP 

Pixmaps;  the  application  creates  a  pixmap  and  gives  it  a  location  (in  meters). 
TACTMAP.PICTURE 

Pictures;  the  application  provides  a  definition  using  the  picture  language  described 
below,  GCs,  and  coordinate  system  transforms. 

TACTNAP.DRAHI 

Objects  the  application  draws  itself;  the  application  provides  a  function  which  is  called 
to  draw  the  object  whenever  the  map  is  updated. 

TACTMAP.TEXT 

Text;  the  application  provides  a  the  string,  location,  GC,  and  some  options. 
TACTMAP.BGR 

BGR  Icons;  the  application  provides  an  object  type,  an  optional  definition  using  the 
BGR  language,  a  GC,  location  (in  meters),  a  call  sign,  and  rotation. 
TACTI1AP.LIIE.IKTERVIS 

Line  intervisibility;  the  application  provides  a  two  points  the  viewers  agl,  the  targets 
agl,  the  targets  height  and  width,  the  treejopadty,  and  any  vehicles  between  the  two 
points.  The  visibility  will  be  colored  in  a  line  from  the  first  point  to  the  second  point. 
TACTMAP.AREA.IITERVIS 

Area  Intervisibility;  the  application  provides  a  2-D  center  point,  a  radius,  the  viewers 
the  targets  agl,  the  targets  height  and  width,  the  treejopadty.  The  visibility  will 
be  colored  in  an  area  cirde  defined  by  the  center  point  and  the  radius. 

Individual  attributes  for  each  type  of  object  are  defined  using  the  following  structure: 

typedef  union  tactnap.object.dfn 

i 

struct  tactnap.hypso 

{ 

TACTHAP.HTPSO.KIID  kind; 

}  hypso; 

struct  tactnap.vater 

TACTNAP.SEISITIVE.OPTIOIS  sensitive; 

>  water; 

struct  tactaap.roads 

i 

TACTHAP_SE*SITIVE_OPTIO»S  sensitive; 

>  roads; 

struct  tactaap.trees 
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{ 

TACTMAP.SEMSITIVE.OPTIOMS  sensitive; 
uint32  wash; 

>  trees; 

struct  tactaap.buildings 

TACTMAP.SEMSITIVE.OPTIOMS  sensitive; 

>  buildings; 

struct  tactnap.pipelines 

TACTMAP.SEMSITIVE.OPTIOMS  sensitive; 

>  pipelines; 

struct  tactaap.political 

TACTMAP.SEMSITIVE.OPTIOIS  sensitive; 

>  political; 

struct  tactaap.railroads 

{ 

TACTMAP.SEMSITIVE.OPTIOMS  sensitive; 

>  railroads; 

struct  tactmap.powerlines 

{ 

TACTMAP.SEMSITiVE.OPTIOMS  sensitive; 

>  poser lines; 

struct  tactaap.contours 

float 64  minor .spacing; 
floated  waj or .spacing; 

>  contours; 

struct  tactmap.towns 

TACTMAP.SEMSITIVE.OPTIOMS  sensitive; 

>  towns; 

struct  tactmap.grids 

int32  interval; 
uint32  label .mask; 

>  grids; 

struct  tactaap.linear 

{ 

TACTMAP.SEMSITIVE.OPTIOMS  sensitive; 
LineStyle  style; 
uintie  dashed; 
uintl6  thickness; 

uint32  forward. arrow; 
uint32  backward. arrow; 
uint32  width; 

CC  gc; 

int32  n_ vertices; 
float64  ^vertices; 
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>  linear; 

struct  tactaap.pixnap 

< 

TACTKAP.SEMSITIVE.OPTIOIS  sensitive; 
float64  x,  y; 
uint32  width; 
uint32  height; 

Pixnap  pixaap; 

>  pixnap; 

struct  tactnap.picture 

{ 

TACTMAP.SEISITIVE.OPTIOMS  sensitive; 
uint32  dashed; 

READER.OIIOX  *dfn; 

int32  nun.gcs ; 

GC  gee [TACTMAP.MAI.GCS] ; 
floated  Magnification; 
char  *strinc; 
int32  highlight; 

int32  nua.csysteas ; 
struct  tactmap.csystam 

int32  parent.systan; 
floated  angle; 
floated  dimensions [2] ; 
floated  origin [2]; 

>  csysteas [TACTMAP.MAX.CSYSTEMS] ; 

>  picture; 

struct  tactnap.drawn 

TACTKAP.SEISmVE.OPTIOIS  sensitive; 
TACTNAP.DRAW.CALLBACK  draw; 

ADDRESS  drav.arg; 

>  drawn; 

struct  tactmap.text 

i 

TACTMAP.SEISITIVE.OPTIOMS  sensitive; 
GC  gc; 

XFontStruct  *f ont. struct ; 
floated  x,  y; 
uintS2  see.through; 

TextAlignnent  alignment; 
intie  horizontal.of f set ; 
intie  vertical.offset; 
char  estring; 

>  text; 

struct  tactnap.bgr 

{ 

TACTMAP.SEISITIVE.OPTIOMS  sensitive; 
floated  x,  y; 
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float64  rotation; 

int32  override; 

READER.OIIOR  *dfn; 

Ob j  ectType  ob j  act .type ; 
int32  size; 

int32  line.thidmeee; 

uint32  dashed; 

char  call_signCTACTNAP.NAX.CALL.SIGI] ; 

int32  highlight; 

GC  gc; 

>  bgr; 

struct  tactaap.line.intervis 

floated  point 1 [2]; 
floated  point2[2] ; 
floated  viever.agl; 
floated  target.agl; 
floated  target.sidth; 
floated  target_height; 
floated  tree.opacity; 
int32  n.veh; 

CTDB.VEHICLE.LOCATIOI  «veh; 
int32  ignore 1; 
int32  show .per cent ages ; 
int32  grid. interval; 

>  line.intervis; 

struct  tactBap.area.intervis 

{ 

floated  center .point [2] ; 
floated  radius; 
floated  viever.agl; 
floated  target.agl; 
floated  target. height; 
floated  target .width; 
floated  tree.opacity; 

>  area.intervis; 

/*  Generic  reference  to  a  sensitive  class  */ 
TACTNAP.SENSITIVE.OPTIOIS  sensitive; 

>  TACTNAP.OBJBCT.DFI ; 


With  only  a  few  exceptions  (TACTNAP.HYPSO,  TACTNAP.CONTOURS,  and  T ACTMAP. GRIDS ) ,  any 
feature  can  be  made  sensitive.  The  specific  options  are  specified  with  the  following  structure: 


typedef  struct  tactaap.sensitive.options 

{ 

SISTVE.CLASS  *class; 


uintlfi 

ADDRESS 


instance;  /•  Ignored  for  terrain  features  */ 
user. data; 
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>  TACTMAP. SENSITIVE. OPTI OHS ; 

See  libSensitive  for  the  meaning  of  these  attributes  (see  section  'Overview'  in  LibSensitive  Pro¬ 
grammer’s  Manual).  The  class,  instance,  and  user.data  are  up  to  the  application  to  define. 
Note  that  for  terrain  features,  only  the  class  and  user.data  will  be  passed  back  in  the  callback; 
the  instance  will  be  changed  to  the  libQuad  ID  for  that  object. 

The  instance  information  given  by  the  application  is  only  16  bits,  whereas  libSensitive  provides 
32.  This  is  because  libTactMap  often  needs  to  create  many  sensitive  objects  for  a  single  user-defined 
object  (such  as  a  LINEAR  object,  which  is  made  up  of  many  segments  and  vertices).  LibTactMap 
provide  macros  to  help  applications  interpret  the  instance  value  received  in  the  SISTVE_CALL_DATA 
of  a  libSensitive  gesture  or  excited  callback: 

TACTHAP.IISTA*CE.TO_USER_ I«STA*CE ( call . dat a- > instance) 

Extracts  the  16  bits  of  instance  information  provided  by  the  user  from  the  32  bit  number 
passed  from  libSensitive. 

TACTNAP_IISTAICE_TO_IVDEX(call.data->instance) 

Extracts  the  libQuad  feature  index  from  the  32  bit  instance  number  passed  from  lib¬ 
Sensitive. 

TACTKAP_IS_VERTEZ(call.data->instance) 

If  the  TACTHAP.CLASS  of  the  object  is  TACTKAP.LHEAR,  this  reveals  whether  the  user 
clicked  on  a  vertex  of  the  line. 

TACTHAP.IS.SEGHEIT(call.data->iiistanca) 

If  the  TACTHAP.CLASS  of  the  object  is  TACTHAP.LIKEAR,  this  reveals  whether  the  user 
clicked  on  a  segment  of  the  line.  It  is  the  logical  NOT  of  TACTMAP.IS.VERTEX. 
TACTMAP_IVDEZ(call_data-> instance) 

If  the  TACTHAP.CLASS  of  the  object  is  TACTHAP.LIREAR,  this  reveals  the  index  of  the 
vertex  (numbered  from  0,  as  specified  in  the  vertices  field  of  the  object  definition)  or 
segment  (numbered  from  0  —  segment  n  connects  vertex  n  to  vertex  n+1)  which  was 
selected. 


Other  fields  of  the  object  definition  have  the  following  meanings: 
hypso.kind 

One  of  the  following  values: 

TACTMAP.DXTHER.HYPSO 

Dithered  altitude  map  (higher  elevations  are  more  dense). 
TACIHAP.COLOR.HYPSO 


Chapter  1:  Overview 


7 


Color  altitude  map  (altitude  ranges  are  represented  by  color  bands;  higher 
altitudes  within  a  band  are  brighter). 

trees .Bask 

A  bitwise  OR  of  the  following  choices: 

TACT1UP_TREE.CAI0PIES 

Tree  canopies  (drawn  as  a  hatched  polygon) 

TACTMAP.TREE.LIMES 
Tree  lines 

TACTMAP.TREE. INDIVIDUAL 

Individual  trees  (drawn  as  little  X’s) 

contours .ninor.spaclng 
contours .naj or. spacing 

A  contour  line  is  generated  every  adnor.spacing  meters  in  altitude.  Those  which  are 
(roughly)  evenly  divisible  by  najor.spacing  are  emphasized. 

grids. interval 

Interval  between  grid  lines  in  meters.  This  is  generally  a  multiple  of  10. 

grids . label_mask 

Specifies  which  sides  of  the  map  to  label,  using  bits  defined  by  libCoordinates  (bitwise 
OR  the  selection  into  a  mask): 

•  COORD.LABEL.LEFT 

•  COORD.LABEL.RIGHT 

•  C00RD.LABEL.T0P 

•  COORD.LABEL.BOTTOM 
linear. style 

Line  style  defined  by  the  persistent  object  protocol 
(‘coasKm/include/protocol/p.po  .h’): 

LSplain  Plain  line 
LSfzontA,  LSfrontB 

Fronts  (semicircles  facing  left  (A)  or  right  (B)) 

LSainefield,  LSadnef  ieldAT,  LSninefieldAP 

Generic,  anti-tank,  and  anti-personnel  minefields  (a  bounding  box  with 
various  kinds  of  circles  inside) 

LSbern  Berm  (a  collection  of  intersecting  semicircles) 

LSATDitchA,  LSATDitchB 

Anti-tank  ditches  (a  line  with  triangle-shaped  teeth  facing  left  (A)  or  right 

(B)) 

LSfortification 

Fortification  (looks  something  like  a  square  wave) 
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LSwire  Wire  (a  line  with  little  X’>  on  it) 

linear. dashed 

Indicates  if  lines  should  be  drawn  using  a  dashed  GC. 

linear . thickness 

Indicates  the  pixel  thickness  of  lines 

linear . forward. arrow 
linear .backward. arrow 

Indicates  whether  arrows  should  be  placed  on  the  ends  of  the  line, 
linear. width 

Width  of  the  line  (only  used  few  minefield  variants) 

linear .gc 

The  GC  to  use  for  drawing  (some  attributes,  such  as  line  width,  will  be  modified).  The 
most  important  attribute  set  by  the  application  is  foreground  color. 

linear . n. vert ices 

Specifies  how  many  vertices  are  used  to  define  the  line, 
linear . vertices 

Pointer  to  x  y  x  y...  format  list  of  vertices.  The  contents  of  this  array  are  copied,  so  it 
is  safe  to  point  this  to  a  local  variable  when  calling  tactnap.create.ob j  act  ( ) .  The 
size  of  this  array  should  be  (linear  .n.vertices*2*sizeof (floated)). 

pixaap.x,  pixnap.y 

The  location  of  the  pixmap  (in  map  coordinates  —  meters). 

pixnap.width,  pixnap. height 

The  size  of  the  pixmap  (in  screen  coordinates  —  pixels). 

pixnap. pixnap 

The  pixmap  to  copy  to  the  screen  (assumes  pixmap  origin  0,0  for  the  copy), 
picture. dashed 

Indicates  if  lines  should  be  drawn  using  a  dashed  GC. 
picture. dfn 

The  definition  of  the  picture,  which  is  described  with  the  following  language: 

((<interior  GC  index >  ;;  -1  to  onit  interior 

<bordar  GC  index>  ;;  -1  to  onit  border 

< coordinate  systen  index> 

<  instruction 
< instruct ion> 

e  e  • 

) 

•  •  • 

) 

< instruct ion>  is  one  of  the  following: 
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(block  xO  yO  xl  yi  x2  y2  ...) 

(line  width  xO  yO  xl  ji  ...) 

(disc  center.x  center.y  radius  [x  I  y  I  ■]) 

(circle  width  center _x  center.y  radius  [x  I  y  I  ■]) 

(label  center.x  center.y) 

x  and  y  values  are  always  relative  to  the  dimensions  passed  in  for  the  coordinate  system; 
width  values  are  in  meters;  and  radius  values  can  be  relative  to  either  dimension  (x 
or  y)  or  in  meters  (a). 

picture .  mouses 

The  number  of  GCs  provided  for  drawing  this  picture, 
picture. ges 

The  GCs  used  to  draw  the  picture, 
picture. nagnificat ion 

Picture  magnification  (1.0  ==  actual  size,  2.0  ==  twice  as  big,  etc.).  Use  0.0  to  treat 
the  units  of  definition  as  pixels  rather  than  meters. 

picture. string 

The  string  to  use  for  labels. 

picture. highlight 

Flag  indicating  if  the  picture  is  highlighted  (non-zero),  and  if  so,  index  of  the  gc  to  use. 
picture  .nuaLCsysteas 

The  number  of  coordinate  systems  provided  for  drawing  this  picture  (must  be  >=  1). 
picture . csysteos 

last  of  coordinate  systems.  The  first  is  relative  to  world  coordinates;  the  rest  are 
relative  to  the  first.  A  coordinate  system  is  made  up  of  the  following  pieces: 

pareat.systea 

The  index  of  the  parent  coordinate  system.  Use  this  one’s  index  to  be 
patented  by  world.  Note  that  a  system  may  not  reference  a  parent  with  a 
higher  index  than  its  own. 

angle  The  rotation  of  the  coordinate  system.  0  is  down  the  Y  axis  of  the  ref¬ 
erence  system,  and  the  angle  (in  radians)  increases  in  a  counter-clockwise 
direction. 

dimensions 

The  scaling  factor  to  apply  to  the  X  (width)  and  Y  (length)  dimensions 
(allows  definition  of  generic  pictures  which  are  stretched  to  portray  an 
individual  vehicle). 

origin  The  center  of  the  coordinate  system,  relative  to  the  reference  system. 

drawn. dr aw 


Function  to  call  to  draw  this  object. 
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drum .  drav.arg 

Single  argument  to  pass  to  the  dram. draw  function, 
text  .gc  The  GC  to  use  for  drawing  the  text.  The  most  important  attributes  set  by  the  appli¬ 
cation  are  foreground  color,  background  color  and  font, 
text . font .struct 

The  font  metrics  for  the  font  used  in  text  .gc.  If  MULL  is  passed,  libTactMap  will  look 
up  the  XfontStruct  on  it  own,  however,  this  requires  a  query  of  the  X  server,  and  could 
thus  hurt  performance.  If  the  application  will  not  be  changing  the  font  frequently,  it 
is  better  if  this  is  specified. 

An  application  can  get  the  ZPontStruct  on  its  own  using 

ZQueryFont (display ,  GContextFronGC(gc)).  Note  that  this  function  allocates  mem¬ 
ory,  so  if  an  application  changes  the  font  used  for  a  text  object,  it  should  free  the  old 
structure  with 

XFreeFont Inf o( FULL ,  font. struct ,  1). 
taxt.x,  text. y 

The  location  of  the  text  reference  point  (in  map  coordinates  —  meters), 
text . see.through 

Whether  the  text  should  be  see-through.  If  FALSE  a  block  around  the  text  will  be  filled 
with  the  background  color  of  the  text.gc  before  drawing,  as  with  ZDravInageString. 
text,  alignment 

Text  alignment  defined  by  the  persistent  object  protocol 

('camon/include/protocol/p.po.h’).  The  anchor  point  of  displayed  text  is  set  via 
this  argument. 

text .  horizontal  .off set ,  text,  vert  leal  .off  set 

Pixel  distance  offsets  which  are  applied  after  the  text  location  is  converted  from  meters 
to  screen  coordinates.  Positive  values  are  right  and  up. 
text. string 

The  text  to  display.  A  TOLL  string  is  acceptable.  Embedded  newlines  are  handled 
correctly. 

bgr.x,  bgr.y 

The  location  of  the  icon  (in  map  coordinates  —  meters), 
bgr  .rotation 

The  rotation  of  the  icon.  0  is  North,  and  the  angle  (in  radians)  increases  in  a  counter¬ 
clockwise  direction, 
bgr. override 

If  TRUE,  use  the  supplied  bgr.dfn  to  draw  the  icon.  Otherwise,  drawn  the  icon  based 
on  an  algorithmic  interpretation  of  the  object. type. 

bgr.dfn  An  optional  collection  of  character  strings  to  be  parsed  by  libBGR  to  draw  the  icon. 

This  field  is  only  used  if  bgr. override  is  FALSE;  This  definition  is  in  the  format  as 
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described  by  libBGRDB  (see  section  ‘Overview’  in  LibBGRDB  Programmer’s  Manual), 
bgr. object .type 

This  specifies  the  object -type  of  the  object  represented  by  this  icon.  This  field  is  only 
used  if  bgr. override  is  FALSE. 

bgr. size  This  specifies  the  approximate  BGR  size  of  the  icon  in  pixels.  LibBGR  uses  this  to 
calculate  an  actual  size  for  the  icon. 

bgr  .line. thickness 

This  specifies  the  thickness  of  drawn  lines  in  the  icon.  Note  that  the  thicker  the  lines, 
the  longer  libBGR  takes  to  draw  something.  An  odd  numbered  thickness  (typically  3) 
works  best. 

bgr. dashed 

Indicates  if  the  icon  should  be  drawn  dashed, 
bgr.call.sign 

An  optional  null-terminated  string  to  be  drawn  as  part  of  the  icon, 
bgr. highlight 

Flag  indicating  if  the  icon  is  highlighted. 

bgr.gc  The  GC  to  use  for  drawing  the  icon.  The  most  important  attributes  set  by  the  appli¬ 
cation  are  foreground  color,  background  color  and  font. 

line.intervis .  point  1 ,  line.intervis  .point2 

Specifies  the  end  points  of  the  intervisility  line. 

line.intervis. viewer.agl,  line.intervis. target _agl 

Specifies  the  viewer  and  target  positions  agl  ("above  ground  level"). 

line,  intervis .  target  .width ,  line.intervis  .target  .height , 

Specifies  the  height  and  width  of  the  target  for  visibility  calculations. 

line.intervis . tree.opacity 

Specifies  reduction  of  visibility  resulting  from  trees.  This  number  is  a  percentage  be¬ 
tween  0  and  1. 

line.intervis .n.veh 

Specifies  number  of  vehicles  passed  in  the  vehicle  structure, 
line.intervis . veh 

Specifies  the  vehicles  to  use  in  the  intervisibility  calculation, 
line.intervis . ignore 1 

Specifies  a  vehicle  to  ignore.  This  is  used  when  performing  a  vehicle  to  vehicle  inter¬ 
visibility  calculation  to  ignore  the  vehicle  we  are  looking  at. 

line.intervis . shov_percentages 

Specifies  whether  we  display  should  show  percentages.  Used  to  determine  whether  a 
point  to  point  or  vehicle  visibility  is  being  calculated. 
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grid. interval 

Specifies  the  current  grid  interval  on  the  screen.  Used  to  determine  how  to  draw  the 
tick  marks  on  the  visibility  line. 
area_intervis . center .point 

Specifies  the  center  point  for  the  area  intervisibility. 

area_intervis . radius 

Specifies  the  radius  of  the  area  intervisibility 
area_interris.viever.agl,  area.intervis. target. agl 

Specifies  the  viewer  and  target  positions  agl  ("above  ground  level"). 
area.intervis  .target .width,  area.intervis  .target .height , 

Specifies  the  height  and  width  of  the  target  for  visibility  calculations. 
area.intervis .tree .opacity 

Specifies  reduction  of  visibility  resulting  from  trees.  This  number  is  a  percentage  be¬ 
tween  0  and  1. 

The  drawn. draw  callback  should  be  defined  as  follows: 


void  drav.callbackf widget,  dravable,  drav.arg,  boundary) 
Vidget  widget; 

Pinup  dravable; 

ADDRESS  drav.arg; 

ZRectangle  *boundary; 


The  function  should  draw  onto  the  window  XtVindov(vidget),  and  return  the  boundary  of 
what  was  drawn  in  boundary.  It  is  the  application's  responsibility  to  determine  if  the  object  is 
visible  (hint:  use  tactaap_nap_to. screen).  An  object  which  is  not  drawn  (probably  because  it  is 
off  the  screen)  should  return  a  boundary  with  width  and  height  of  0. 
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3  Examples 


A  complete  example  can  be  found  in  the  test  program  ‘test.c’  in  the  libtactmap  source  direc¬ 
tory.  A  couple  brief  examples  are  given  here. 


Assuming  the  tactical  map  has  been  created,  display  roads,  and  make  them  hot: 


extent  TACTMAP.PTR  ay.tactaap; 
extent  SISTVE. CLASS  road. class ; 

TACTNAP.OBJECT.Dra  dfn; 

TACTMAP.0BJECT.PT11  roads; 

SISTVE.IHT. CLASS  (road. class) ; 

road. class. sensitive  »  1; 

road.class.hot  ■  1; 

bxero(ftdfn,  sixeof (dfn)) ; 

dfn. roads. sensitive. class  •  Aroad.dass; 

roads  ■  tactaap.create.obj  act  (ay.tactaap,  TACTMAP.ROADS,  ftdfn); 
tactnap.add. object (ny.tactaap ,  roads) ; 


To  translate  the  location  of  a  mouse  dick  to  map  coordinates: 


extent  TACTMAP.PTR  ny.tactaap; 
int32  screen.!,  screen.y; 
floated  eap.x,  aap.y; 

screen.!  ■  xevant->xbutton.x; 
screen_y  ■  xevent->xbutton.y; 

tactmap. screen. to.nap (ay.tactaap,  screen.!,  screen_y,  taap.x,  ftasp.y) ; 
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3  Function* 


The  following  sections  describe  each  function  provided  by  libtactmap,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


3.1  tactmapJnit 

void  tactnap.initO 
taap.init  initializes  libtactmap. 

Call  this  function  before  any  other  libtactmap  functions. 


3.2  tactmap-create 


TACTMAP.PTR  tactaap. create (widget ,  sensitive,  sennit ive_eraae_gc, 

refresh,  tcc,  ctdb,  quad.dat a) 

Midget  widget ; 

SlSTVE.tniDOM.PTR  sensitive; 

GC  seas it ive. erase.gc ; 

TACTHAP.REFRESH.CALLBACK  refresh; 

C00RD.TCC.PTR  tcc; 

CTDB  *ctdb; 

QUAD.DATA  * quad .data; 


‘widget’  Specifies  the  widget  for  drawing 
‘sensitive’ 

Specifies  the  sensitive  window 
‘sensitive. erase_gc’ 

Specifies  the  GC  used  by  libsensitive  for  erasing 
‘refresh’  Specifies  the  function  to  rail  at  beginning  and  end  of  map  refresh 
‘tcc’  Specifies  the  coordinate  system  of  the  terrain  database 
‘ctdb’  Specifies  the  CTDB  format  terrain  database 
‘quad.dat  a’ 

Specifies  the  libQuad  format  terrain  database 
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tactaap. create  creates  a  tactical  map.  The  map  starts  with  no  features  displayed.  The 
widget  specifies  the  drawing  area  (libtactmap  posts  its  own  resize,  expose,  etc.,  handlers).  The 
sensitive  window  should  be  created  with  a  call  to  anatve.createO  (see  section  ‘snstvejc  reate’  in 
LibSensitive  Programmer’s  Manual). 

The  refresh  callback,  if  non-NULL  should  be  declared  as  follows: 


void  ref rash. callback ( t  actaap ,  refreshing) 

TACTMAP.PTR  t actaap ; 

int32  refreshing;  /*  TRUE  at  beginning,  FALSE  at  end  */ 


3.3  tactmap_get_color 


Pixel  tactaap .get .color (tactaap ,  class) 
TACTMAP.PTR  t actaap; 

TACTMAP.OBJECT.CLASS  class; 


‘tactaap’  Specifies  the  tactical  map 
’class’  Specifies  the  terrain  feature  class 

tactaap.get.  color  returns  the  pixel  value  of  a  color  used  when  drawing  objects  of  the  passed 
class.  Pass  -1  to  get  the  background  color. 


3.4  tnctmap-setjscale 


void  tactaap.set .scale (tactaap,  scale) 
TACTMAP.PTR  tactaap ; 
f loat64  scale ; 


’tactaap’  Specifies  the  tactical  map 
’scale’  Specifies  the  map  scale 


tactaap.set. scale  sets  the  map  scale  to  l:scale. 
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3.5  tnctmapjiet^center 


▼old  tactaap.set. center (tactaap,  x,  y) 
TACTMAP.PTR  tactaap; 
lnt32  x; 

int32  7; 


‘tactaap’  Specifies  the  tactical  map 

‘x,  7’  Specify  the  new  center  (in  meters) 


tactaap.set.center  sets  the  map  center. 


3.6  tactmap .screen jto jnap 


▼old  tactaap_ecreen.to.aap (tactaap.  screen.x,  screen.y,  aap.x,  aap.y) 
TACTMAP.PTR  tactaap; 
int32  ecreen.x; 

int32  acreen_7; 

float64  *nap_x; 
floated  *aap_y ; 


‘tactaap’  Specifies  the  tactical  map 
‘ecreen.x,  ecreen_7’ 

Specifies  a  point  in  screen  coordinates  (pixels) 

*aap.x,  aap.7’ 

Returns  the  corresponding  poing  in  map  coordinates  (meters) 
tactaap.screea_to.aap  converts  a  screen  location  to  a  map  location. 


3.7  tactmap_map.to_screen 


int32  tactaap_aap_to_screen(tactaap,  aap.x,  aap.y,  ecreen.x,  screen.y) 
TACTMAP.PTR  tactaap; 
floated  aap.x; 

floated  aap.y; 

int32  escreen.x; 

int32  * screen. 7; 
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‘tactaap’  Specifies  the  tactical  map 
‘aap.x,  aap.j' 

Specifies  a  point  in  map  coordinates  (meters) 

‘screen.x,  acreen.y’ 

Returns  the  corresponding  point  in  screen  coordinates  (pixels) 

tactaap_aap.to_screen  converts  a  map  location  to  a  screen  location.  The  return  value  indi 
cates  whether  the  point  is  visible  (TRUE  if  visible). 


3.8  tactmap^>ixeluofifset 


voir*  .actaap.pixel.  "ff  .  vt  (tactaap ,  acraan.dx,  screan.dy ,  aap.dx,  aap.dy) 
TACTMAP.PTR  tac 
la*  "2  acrw^f  ix; 

in'.  '2  screen.dy; 

float64  *nap_dx; 

float64  *aap_dy; 


‘tactaap’  Specifies  the  tactical  map 

‘acraan.dx,  acraan_dy’ 

Specifies  an  offset  in  screen  coordinates  (pixels) 

‘aap.dx,  aap.dy’ 

Returns  the  corresponding  offset  in  map  coordinates  (meters) 


tactaap.pixel.off  set  converts  an  offset  in  screen  coordinates  to  the  equivalent  offset  in  me¬ 
ters. 


3.0  tactmap .locale 


void  tactaap_locale(tactaap,  cantar.x,  cantar.y,  width,  height) 
TACTHAP.PTR  tactaap; 
float64  *center.x; 
float64  *center_y; 

floated  * width; 

floated  'height ; 


‘tactaap’  Specifies  the  tactical  map 
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‘  center _x,  center .y* 

Returns  the  coordinates  of  the  map  center  (meters) 
‘width*  Returns  the  map  width  (meters) 

‘height*  Returns  the  map  height  (meters) 


tactaap.locale  returns  center  and  size  of  map  in  meters. 


3.10  tactmap. world  .view 

void  t actaap.wor Id. wiew (tactaap,  world.wiew.on) 

TACIHAP.PTR  tactaap; 
ini 32  world.wiew.on; 

‘tactaap*  Specifies  the  tactical  map 
‘world.wiew.on* 

Specifies  whether  world  view  mode  should  be  enabled 

tactaap.world.wiew  puts  the  tactical  map  in  a  mode  where  the  grid  lines  for  the  entire  database 
are  shown,  and  a  box  representing  the  viewport  is  laid  on  top. 


3.11  tactmap_get.acale 


floated  tactaap.get. scale (tactaap,  width,  height) 
TACTIUP.PIR  tactaap; 
int32  width; 

int32  height; 


‘tactaap’  Specifies  the  tactical  map 

‘width’  Specifies  the  requested  sub-width  (pixels) 

‘height’  Specifies  the  requested  sub-height  (pixels) 


tactaap .get.scale  determines  the  map  scale  which  would  encapsulate  a  box  of  the  passed  size 
(in  pixels). 
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3.12  tactmap_create  ^object 

TACTMAP.OBJECT.PTR  tactaap.create.obj ect (tactaap,  class,  dfn) 
TACTMAP.PTR  tactaap; 

TACTKAP.OBJECT. CLASS  class; 

TACTNAP.OBJECT.Dni  *dfn; 

‘tactaap’  Specifies  the  tactical  map 
‘class’  Spedfies  the  object  class 

‘dfn’  Specifies  the  initial  definition  of  the  object  to  be  created 

t actaap. crest e. ob j  ect  creates  an  object  which  can  be  placed  on  the  tactical  map. 

See  Section  3.13  [tactmap'destroy 'object],  page  20. 

See  Section  3.14  [tactmap'add'object],  page  20. 

See  Section  3.15  [tactmap'remove  object),  page  21. 

See  Section  3.16  [tactmap'update'object],  page  21. 


3.13  tactmap^destroy .object 

▼old  t actaap. destroy _obj  ect (tactaap ,  obj) 

TACTMAP.PTR  tactaap; 

TACTNAP.OBJECT.PTR  obj ; 

‘tactaap’  Specifies  the  tactical  map 
‘object’  Specifies  the  object  to  add 

tactaap  .destroy,  obj  ect  destroys  an  object  created  with  tactaap.create.object  and  frees 
any  memory  associated  with  that  object. 

See  Section  3.12  [tactmap'create  object],  page  20. 

See  Section  3.14  [tactmap'add'object],  page  20. 

See  Section  3.15  [tactmap'remove  object],  page  21. 

See  Section  3.16  [tactmap'update'object],  page  21. 


3.14  tactmap^add_object 


SP  r  r  r  „  |  f  t  r  r  r  r 
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void  tactnap.add.obj ect (tactaap ,  object) 

TACTNAP.PTR  tactaap; 

TACTNAP.OBJECT.PTR  object; 

‘tactaap’  Specifies  the  tactical  map 
‘object*  Specifies  the  object  to  add 

tactaap. add. object  adds  an  object  (created  with  tactaap.create.object)  to  the  map  dis¬ 
play  list. 

Section  3.12  [tactmap’create’object],  page  20. 

Section  3.13  [tactmap’destroy'object] ,  page  20. 

Section  3.15  [tactmap'remove  object] ,  page  21. 

Section  3.16  [tactmap'update'object],  page  21. 


.5  tactmap-remove-object 

▼old  tactaap.reaove.obj ect  (tactaap,  object) 

TACTNAP.PTR  tactaap; 

TACTNAP.OBJECT.PTR  object; 

:taap’  Specifies  the  tactical  map 
ect’  Specifies  the  object  to  remove 

actaap.reaove.object  removes  an  object  from  the  map  display  list. 

Section  3.12  [tactmap'create’object],  page  20. 

Section  3.13  [tactmap'destroy ’object],  page  20. 

Section  3.14  [tactmap'add’object],  page  20. 

Section  3.16  [tactmap'npdate’object],  page  21. 


3.16  tactmap_updatejobject 


void  tactaap.update.obj ect (tactaap,  object,  dfn) 
TACTNAP.PTR  tactaap; 

TAC1NAP.0BJECT.PTR  object; 
TAC1MAP.0BJECT.DFB  *dfn; 


rrrr 
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‘tactaap’  Specifies  the  tactical  map 
‘object’  Specifies  the  object  to  update 
‘dfn*  Specifies  the  new  object  definition 

tactaap.update.ob j  ect  changes  the  attributes  of  an  existing  object. 

Section  3.12  [tactmap’create  object],  page  20. 

Section  3.13  [tactmap'destroy 'object],  page  20. 

Section  3.14  [tactmap'add’object],  page  20. 

Section  3.15  [tactmap'remove ’object],  page  21. 


3.17  tactmap_add_transient_object 

▼old  tactaap. add. transient .object (tactaap,  object) 

TACTMAP.PTR  tactaap ; 

TAC11(AP.0BJECT.PTR  object; 

*tactaap*  Specifies  the  tactical  map 
‘object*  Specifies  the  object  to  add 

tactaap_add.transiaat.object  adds  an  object  (created  with  tactaap.create.object)  to 
the  map  display  list.  This  is  identical  in  operation  to  tactaap.add_object,  except  the  object 
will  be  displayed  on  top  of  the  pixmap  where  other  objects  are  placed.  Transient  objects  must  be 
refreshed  frequently,  since  popups  and  window  drawing  may  erase  them. 


3.18  tactmapjticlc 


▼old  tactaap.tick (tactaap,  aax.tiae.slice) 
TACTMAP.PTR  tactaap; 
uint32  aax.tiae.slice; 


‘tactaap’  Specifies  the  tactical  map 
‘aax.tiae.slice’ 

Specifies  the  maximum  run  time  this  tick 


tactaap.tick  updates  the  map  image.  Call  this  function  periodically  to  redraw  the  map  (if 
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no  redraw  is  needed,  the  function  will  just  return),  naz_tine.il ice  specifies  the  amount  of  time 
which  is  acceptable  to  spend  redrawing  this  tick.  If  drawing  operations  exceed  this  time  allotment, 
the  refresh  will  not  be  completed  until  the  next  tick  or  later. 


5.19  tnctmnp -redrawing 

int32  tactnap.redrauingC  tactnap) 

TACTMAP.PTR  tactnap; 

‘tactnap’  Specifies  the  tactical  map 

tactnap.redravisg  returns  TRUE  if  the  map  is  in  the  process  of  refreshing  itself.  Drawing  on  a 
map  which  is  in  this  state  will  probably  disappear  on  the  next  call  to  tactnap.tickO. 

See  Section  3.2  [Argument  refreah],  page  15. 

3.20  tnctmnp jrefreah jnon jfcerrnin 

▼old  tactnap_refresh_non_tirain(tactnap) 

TACTMAP.PTR  tactnap; 

‘tactnap’  Specifies  the  tactical  map 

tactnap_rafresh_non_terrain  runs  through  all  non- terrain  objects  and  redraws  them.  This 
may  be  called  after  editing  operations  to  correct  accidental  erasures. 

3.21  tnctmnp  jqundjdntn 

QUAD.OATA  •tactnap.quad.data(tactnap) 

TACTMAP.PTR  tactnap; 

‘tactnap’  Specifies  the  tactical  map 

tactnap.quad.data  returns  the  libQuad  quad  data  structure  used  by  a  tactical  map. 


24 


LibTactMap  Programmer’s  Guide 


S.22  tactmap .bundle-changes 

▼old  tactaap_bundle_changes(tactup) 

TACTIUP.PTll  t setup; 

‘t setup’  Specifies  the  tactical  map 

tactup.bundle.  changes  sets  do.refreah  to  delay  redrawing.  This  is  used  in  the  cases  where 
there  are  many  changes  made  to  the  tactmap  and  the  redrawing  should  wait  until  the  tactmap  is 
ticked  again. 
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4  Resource* 


Various  Attributes  of  the  map  display  can  be  customized  on  a  per-X-server  basis  through  the 
use  of  resources.  These  are  typically  set  in  a  user’s  ‘.zresourcea’  file.  For  example,  to  draw  blue 
(instead  of  green)  trees,  the  entry  in  the  * .  zresourcea’  file  would  read: 


•TacticalMap.tree:  blue 


The  full  list  of  resource  names,  default  values,  and  descriptions  follows: 

Jkground  (default:  GrayTS) 

Map  background  color 

hypsoDither  (default:  Black) 

Color  used  for  drawing  hypsometric  dither  patterns 

water  (default:  steelBlue) 

Unfordable  water  color 

fordable  (default:  SkyBlue) 

Fordable  water  color 

noGo  (default:  FireBrick) 

No-go  terrain  color  (only  available  on  a  few  databases) 

slowGo  (default:  GoldB) 

Slow- go  terrain  odor  (only  available  on  a  few  databases) 

road  (default:  Redl) 
color 

tree  (default:  DarkGreen) 

Tree,  tree  line,  and  tree  canopy  color 

building  (default:  Gray25) 

Building  (and  other  structure)  color 

pipeline  (default:  Cyan4) 

Pipeline  color 

political  (default:  OrangeS) 

Color  of  political  boundaries 

railroad  (default :  Black) 

Color  used  for  railroads 

power  line  (default:  Gray  25) 

Color  used  for  powerlines 
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contour  (Mult:  Siuut) 

Coin  need  for  contour  lino*  (minor  arc  drawn  thin,  major  are  drawn  thick) 

torn  (default :  Black) 

Color  naed  to  draw  town  names 

grid  (default:  Black) 

Color  naed  to  draw  grid  line*  and  grid  labels 

coapass  (default:  6710006) 

Color  used  to  draw  North  annotation 

townFont  (default:  XtOefaultFont) 

Font  used  for  town  names 

gridFont  (default:  XtOefaultFont) 

Font  used  for  grid  labels 

hypsoHap  (default :  see  below) 

String  specifying  the  altitude  color  bands.  The  format  is  as  follows: 

(<altitude>  <dark  color>  <bright  color>] • 

The  altitude  specifies  the  lowest  altitude  of  a  color  band.  Altitudes  within  a  band 
are  interpolated  between  the  dark  and  bright  versions  of  the  color.  The  default  is  the 
string: 

"0  6b6c06c  6ccd767  200  6ecec84  6f9f98b  600  6d4b068  6ef c676 
1000  6b87S79  6dS8c8c  2000  6934546  6b3S558  3000  6a99197  OcOaSab 
4000  6bbacc8  6d8c7e7  5000  6cdabb2  6e3bdc5  6000  GraySO  White" 
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1  Overview 


Libtask  is  a  subclass  which  manages  the  association  between  Tank  class  objects  in  the  PO 
database,  and  the  vehicle  subclasses  which  execute  those  tasks.  Each  task  is  identified  with  a  SAF 
model  number  (defined  in  ‘p.safaodels.h’).  When  each  task  library  is  initialized  it  tells  libtask 
of  its  presence  and  passes  information  so  that  libtask  can  execute  the  subclass  when  necessary. 

Libtask  also  provides  utility  functions  which  are  used  by  tasks,  and  by  the  augmented  asyn¬ 
chronous  finite  state  machine  (AAFSM)  code  generator  (see  Chapter  2  [AAFSM  Code  Generator], 
P«g*3). 

Libtask  expects  a  subset  of  the  fallowing  functions  from  each  task: 

Changed  parameters 

This  function  is  called  for  an  executing  task,  just  prior  to  its  tick  if  its  parameters 
changed  in  the  PO  database  since  its  last  tick.  This  is  provided  so  that  tasks  do  not 
need  to  check  their  parameters  every  tick  or  install  object  changed  handlers.  Changes 
to  other  objects  which  are  referenced  by  the  task’s  parameters,  also  trigger  this  event. 
This  event  will  also  be  run  if  a  task’s  parameters  are  overridden  via  a  transparent  task 
frame. 

Predicate 

This  function  is  called  for  enabling  tasks  to  determine  if  their  conditions  have  been 
met.  For  example,  an  enabling  task  which  monitors  crossing  lines,  will  return  TRUE  if 
the  line  has  been  crossed,  FALSE  otherwise.  Tasks  which  are  not  simply  enabling  tasks 
should  pass  a  function  which  indicates  if  they  are  in  their  ended  state.  This  way,  a 
subsequent  task  frame  may  refer  to  an  executing  task  as  its  enabling  task,  to  trigger  a 
transition  when  the  task  completes. 

Start  This  function  is  called  to  start  the  task  execution.  The  start  function  for  each  task 
should  prepare  the  task  for  its  first  tick,  which  will  be  called  immediately  after  the 
start.  This  may  be  called  in  the  following  cases: 

•  When  a  task  is  first  executed,  or  executed  again  after  being  stopped.  In  this  case 
the  state  of  the  task  will  be  not. running  or  ended. 

•  When  a  task  is  resumed,  after  being  Suspended.  In  this  case,  the  state  of  the 
task  will  be  suspended. 

•  When  a  vehicle  migrates  from  another  hardware  platform  while  the  task  is  running. 
In  this  case  the  state  of  the  task  could  be  any  valid  state. 

This  function  is  called  to  tick  the  task  finite  state  machine. 


Tick 
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Stop  This  function  is  called  to  prematurely  stop  execution  of  a  task.  Note  that  the  end 
function  may  be  called  for  a  task  which  is  already  in  its  ended  state. 

Suspend  This  function  is  called  when  a  task  is  suspended  (either  because  an  opaque  frame  was 
pushed  on  top  of  its  frame,  the  suspended  flag  was  set  in  the  task,  or  it  was  removed 
temporarily  from  its  frame  by  its  creator). 

The  preprocessor  program  ‘f  sa2ch’  converts  an  AAFSM  source  file  into  a  C  program  which 
automatically  defines  these  functions,  and  includes  them  in  a  call  to  task_register. 
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2  AAFSM  Code  Generator 


The  AAFSM  code  generator  is  simply  an  ‘ask’  script  which  converts  a  finite  state  machine 
(‘.fan*)  source  file  into  C  code.  The  principle  is  similar  to  that  used  in  ‘yacc’  and  ‘lex’,  where  a 
simple  language  is  used  to  describe  the  structure  of  the  desired  program,  and  fragments  of  C  source 
code  are  used  to  specify  the  details. 

Within  a  ‘.fa’  file,  the  finite  state  machine  is  distinguished  by  the  use  of  the  grave  character 
The  following  sections  explain  the  different  sections  of  the  state  machine  definition. 


2.1  Opening  Comment 

The  opening  comment  is,  of  course,  optional.  It  reminds  readers  of  the  software  of  the  variables 
which  are  available  within  the  state  machine  code  fragments.  It  generally  goes  as  follows: 

/*  lot*  that  the  variables: 

*  int32  vehicle. id; 

*  PO.DB.EITRY  *t ask. entry; 

*  PO.DB.EITRY  *unit .entry; 

*  TaskStateClass  *state.object; 

*  <TASK>.PARAXETERS  tparaeetera ; 

*  <TASK>_ STATE  estate; 

*  <TASK>.VARS  ^private; 

*  are  always  available.  Also  note  that  changes  to  the  state  data 

*  are  automatically  transmitted  on  the  network. 

*/ 

The  name  of  the  parameters,  state,  and  private  structures,  will  differ  between  machines. 

Also,  it  is  customary  to  mention  the  events  which  are  defined,  and  what  they  mean.  The 
following  events  are  required: 

/*  Events: 

* 

*/ 


tick  -  state  machine  tick 
params  -  change  in  parameters 
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2.2  Name  and  Structure  Declarations 

The  state  machine  itself  starts  with  the  opening  grave,  and  the  following  items: 

name  Specifies  the  name  of  the  task.  This  name  will  be  prepended  to  various  function  names 
which  are  generated  automatically,  such  as  .init.f  sm,  .start,  .end,  .suspend,  and 
.ended.  It  is  also  used  when  accessing  the  private  variables,  by  appending  .user. data. handle 
(see  section  ‘ class -get_user_data’  in  LibClass  Programmer’s  Manual).  Finally,  this  naate 
is  used  to  name  the  enumerated  type  for  machine  state  by  appending  .states. 

PARAMETERS 

Specifies  the  structure  used  to  store  parameters  of  the  task.  The  data  portion  of  the 
TaskClass  object  which  corresponds  to  this  task  is  assumed  to  contain  this  structure. 

STATE  Specifies  the  structure  used  to  store  the  task  state.  The  data  portion  of  the 

TaskStateClass  object  which  is  used  by  the  task  is  assumed  to  contain  this  struc¬ 
ture.  This  structure  must  contain  a  variable  called  state  which  is  of  type  enias 
<naae>.state. 

VARS  Specifies  the  structure  used  to  store  private  data  for  the  task.  This  is  the  data  which 
is  attached  to  the  vehicle  executing  the  task  via  its  libdass  user  data  handle. 

For  example,  the  bingo  fuel  task  uses  the  following  declarations: 

< 

ubingofuel  UBIIGOFOEL.PARAMETERS  UBIiGOFUEL.STATE  UBIIGOFUEL.VARS 
The  unit  follow  route  task  uses: 


uflwrte  UFLHRTE.PARAMETERS  UFLWRTE.STATE  UFLVRTE.VARS 


2.3  Sub-taak  Declarations 

Next  are  the  optional  sub-task  declarations.  Subtasks  declarations  describe  the  tasks  which  this 
task  spawns,  and  provide  a  code  fragment  to  fill  in  the  spawned  task’s  parameters.  Each  declaration 
contains  the  following  parts: 


SUBTASK:  Indicates  to  the  code  generator  that  a  subtask  is  being  defined. 
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lane  Provides  a  user-readable  name  which  will  be  used  to  reference  this  task  from  now  on. 
Each  name  must  be  unique. 

■saber  For  each  task  type  spawned,  there  should  be  an  array  in  the  state  structure  to  hold 
the  references  to  these  tasks.  This  specifies  which  member  of  the  structure  is  the  array 
which  holds  installations  of  this  task. 

SAF  Model  Specifies  the  SAF  model  number  of  the  task  being  spawned. 

PARAMETERS 

Specifies  the  structure  of  the  parameters  which  are  used  by  the  spawned  task, 
reference  count 

Specifies  how  many  of  the  reference  slots  are  used  by  the  spawned  task, 
state  initialization  function 

Specifies  a  function  provided  by  the  spawned  task’s  library  to  initialize  the  state  vari¬ 
ables  of  the  spawned  task. 

BCKGRID  If  the  subtask  declaration  line  ends  in  the  keyword  BCKGRID,  the  task  will  be  considered 

to  already  exist  in  the  background,  causing  SPAHK  to  search  for  the  task  instead  of 
creating  it. 

code  fragment 

A  body  of  C  code  which  initializes  or  updates  the  parameters  of  the  spawned  task  from 
this  task’s  parameters,  state,  or  other  information. 

In  addition  to  the  usual  variables,  the  following  additional  variables  may  be  referenced 
within  the  code  body: 

<SUBTASK>  .PARAMETERS  *subtank 

Parameters  of  the  spawned  task,  which  should  be  filled  out  by  the  code 
body 

int32  is.update 

Flag  which  is  set  when  the  code  body  is  running  to  update  an  existing  task, 
due  to  a  par  ana  event  in  the  parent  task. 

EVD.SUBTASK 

Indicates  the  end  of  the  subtask  definition. 

Note  that  the  entire  declaration  up  to  the  code  body  must  be  on  one  line,  however  for  readability, 
some  of  the  declarations  have  been  split  into  two  lines  (the  first  ending  with  ‘V)  in  the  examples 
below. 

For  example,  the  following  was  used  by  a  version  of  unit-level  route  following  to  declare  a 
vehicle-level  route  following  subtask,  and  a  vehicle-level  orbit  subtask: 


SUBTASK:  Yehicle.Follow.Route  vflwrte.taak  SM.VFlvRte  \ 


6 


LibTask  Programmer’s  Guide 


VFLWRTE.PAiUNETERS  1  vflsrte.init.task.state 

{ 

subtask- >rout a  ■  private- >route_ id; 
subtaak-> speed  ■  parsaeters->speed; 
subtaak-> altitude  *  paraaet ers->altitude ; 
subtask- >aove_type  ■  paraaeters->nove_type; 

> 

EVD.SUBTASK 

SUBTASK:  Vehicle.Orbit  vorbit.task  SN.VOrbit  \ 
VORBIT.PARAKETERS  0  vorbit.init.task.state 
< 

float 64  ny.pos [3] ; 

if  Cis.update)  /*  Don’t  change  after  initially  set  */ 

{ 

ent.get.position(vehicle_id(  ay.pos); 
subtask->canter.pt CX]  *  ay.pos [X]; 
subtask->cant er.pt [T]  ■  ay.pos [Y] ; 

> 

subtask- >radius  »  private->paraas->orbit .radius ; 
subtask- > speed  ■  private->paraas->orbit_ speed; 
subtask->altitude  ■  paraaeters-> altitude ; 

EVD.SUBTASK 


2.4  Sub-frame  Declarations 

Those  tasks  which  create  other  task  frames  may  do  so  using  a  sub-frame  declaration.  These 
declarations  have  the  following  format: 

Haste  Provides  a  user-readable  name  which  will  be  used  to  reference  this  task  frame  from 
now  on.  Each  name  must  be  unique. 

a leather  For  each  task  frame  spawned,  there  should  be  an  array  in  the  state  structure  to  hold 

the  references  to  these  task  frames.  This  specifies  which  member  of  the  structure  is  the 
array  which  holds  instatiations  of  this  frame. 

instruction 

Indicates  the  instruction  which  should  be  used  to  install  the  task  frame.  It  must  be 
one  of  the  following: 

TUPopIone 

Push  this  frame  onto  the  stack 
TUPopVonOpaque 
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Pop  all  non-opaque  frames  down  to  the  first  opaque  frame,  then  push  this 
frame 

TXXPopOpaque 

Pop  all  frames  down  to  and  including  the  first  opaque  frame,  then  push 
this  frame 

optional  flags 

Finally,  optional  flag  values  may  be  used: 

opaque  Indicates  that  the  task  frame  should  be  opaque  (if  (Knitted,  the  created 
frames  will  be  transparent). 

destroy  Indicates  that  the  task  frame  should  be  automatically  destroyed  when  it 
completes. 

code  fragpent 

A  body  of  C  code  which  assembles  the  task  frame. 

In  addition  to  the  usual  variables,  the  following  additional  variables  may  be  referenced 
within  the  code  body: 

ObjectID  *unit_id 

Specifies  the  unit  which  will  be  executing  the  task  frame 
int32  which 

Specifies  which  instantiation  of  the  task  frame  is  occurring 
The  body  may  include  defined  subtasks  using  the  directive: 

IMCLUDE:  <Im> 

The  <laae>  specifies  the  name  of  the  task  to  be  included. 

Note  that  the  entire  declaration  up  to  the  code  body  must  be  on  one  line,  however  for  readability, 
some  of  the  declarations  have  been  split  into  two  lines  (the  first  ending  with  ‘V)  in  the  examples 
below. 

For  example,  the  following  were  used  in  a  version  of  the  unit  bingo-fuel  task  to  define  a  return- 
to-base  task  frame. 

SUBTASK:  Unit.Return_To.Base  urtb.task  SH.URTB  \ 

URTB.PARAMETERS  1  urtb.init.task.state 

i 

subtask**  >base  ■  par  east  ers->base; 
subtask->speed  ■  paraaeters->speed; 
subtask->altitude  »  paraaeters*>altitude; 

> 

EVD .SUBTASK 


SUBFRAME:  Returs.To.Base  rtb.taskfraae  TUPopOpaque  opaque  destroy 
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IVCLUDE:  tArlt_lUtt1rB.T0.B4ae 

EVD.SUBFRAHE 


2.5  Criteria  Declarations 

Each  task  may  declare  criteria  under  which  it  will  want  to  control  actuators.  This  information  is 
passed  on  to  libTaskPri,  where  it  is  merged  with  information  from  other  tasks  to  determine  which 
task  controls  each  actuator  during  any  tick  (see  section  ‘taskpri  _registerJbr_group’  in  LibTaskPri 
Programmer’s  Manual). 

For  each  declared  output  criteria,  a  task  implicitly  defines  a  variable  within  the  context  of  the 
tick,  parama,  and  any  other  events.  This  variable  is  set  to  indicate  whether  the  task  has  been 
selected  to  provide  output,  and  is  called  group.enabled. 

For  example,  if  the  prioritization  of  the  weapons  and  sensors  actuators  is  given  by  the  SN_TaskPriority 
parameters: 

(SM.TaskPriority  (tasks 

("sensors"  SX.VTargeter 
SN.VSearch 
) 

("weapons"  SN.VTargeter 
SN.VSearch 
) 


this  means  that  the  tasks  VTargeter  and  VSearch  both  might  want  to  provide  output  to  these 
actuators,  and  VTargeter  has  higher  priority  in  both  cases. 

The  FSM  definition  for  VSearch  might  look  like  this: 


vsrch  VSEARCH.PARAHETERS  VSEARCH. STATE  VSEARCH.VARS 


CRITERIA:  sensors 
TASKPRI .RUIVIVG 
EVD.CRITERIA 

CRITERIA:  weapons 

TASXPRI_AID(TASKPRI.RUII!K,  TASKPRI .SELECTED (SN.VSearch,  "sensors")) 
EVD.CRITERIA 
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tickO 

peraas () 


The  first  criteria  says,  "I  want  to  control  sensors  whenever  I  am  running."  The  second  one  says, 
"I  want  to  control  weapons  whenever  I  am  running,  and  the  task  SM.VSearch  has  control  of  the 
sensors." 


As  a  result  of  these  two  declarations,  there  will  be  two  variables  defined  in  the  context  of  the 
state  machine: 

int32  sensors .enabled; 
int32  weapons .enabled; 

Prior  to  issuing  commands  to  an  actuator,  libvsearch  must  check  to  make  sure  the  corresponding 
flag  is  TRUE. 


2.6  Event  Declarations 

The  next  portion  of  the  state  machine  definition  is  the  declaration  of  events.  At  a  minimum, 
the  events  tick  and  paraas  must  be  defined.  Each  event  starts  with  an  opening  grave,  then  has 
a  name,  and  an  argument  list  (which  may  be  empty).  For  example,  all  tasks  will  start  with  the 
standard  events: 


f 

tickO 

I 

paraasO 

If  a  task  needs  to  define  its  own  events,  those  should  follow.  They  may  take  additional  arguments. 
For  example,  suppose  a  task  has  a  need  for  an  event  called  ay. event  which  takes  an  argument  called 
reason  which  is  of  type  EVEVT.REASOI,  and  an  argument  called  tiae,  which  is  of  type  uint32: 


f 


ay. event (reason,  tiae) 
EVEIT.REASOR  reason; 
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uint32  tins ; 

This  event  can  be  invoked  from  utility  functions  defined  later  in  the  '.fn'  file  as  follows: 

TASI.QPEI_II?OCATIO*(ny.evant.  vehicle.id,  db.  task. id) 
reason,  tiae 
TASK.CL0SE.IIV0C1TI0I 

vehicle.id  specifies  the  vehicle  which  is  executing  the  task;  db  is  a  painter  to  the  PO.DATABASE; 
and  task_id  is  a  pointer  to  the  ObjectID  of  the  task  for  which  the  event  occurred. 

These  macros  expand  to  a  sequence  of  calls  which  find  the  task  and  state  PO  objects,  call  the 
user-defined  event,  and  update  the  task  state  on  the  network,  if  it  changed. 


2.7  Special  Commands 

The  remaining  sections  of  the  state  machine  definition  may  make  use  of  several  special  com¬ 
mands: 

Transitions 

Transitions  to  other  states  are  indicated  as  follows: 

~ne«state;  consents 

nevstate  Is  the  state  to  which  a  transition  should  occur.  Anything  after  the  *;’  is 
assumed  to  be  a  comment  and  is  skipped  by  the  code  generator.  Comments  should  be 
included  at  each  transition  to  describe  the  reason  for  transitioning  (these  comments 
may  be  used  by  automata-drawing  programs). 

Note  that  a  transition  implies  a  return  from  the  event. 

Spawning  Tasks  or  Frames 

Subtasks  and  Subframes  which  were  defined  earlier  in  the  machine  may  be  spawned 
using  the  command: 

SPAN!  <vho>  <*ans>  [<which>] 

vho  is  a  pointer  to  the  ObjectID  of  the  unit  which  is  to  execute  the  task  or  task 
frame.  The  special  value  SELF  may  be  used  to  run  the  task  in  the  current  unit.  lane 
is  the  name  of  the  task  or  task  frame  to  spawn.  The  optional  which  is  a  small  integer 
indicating  which  instantiation  of  the  task  or  task  frame  is  bang  spawned  (it  should  be 
less  than  the  naxinun  specified  in  the  task  or  task  frame  declaration). 
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Stopping  Tasks 

Tasks  which  were  SPAHIed  can  be  stopped  using  the  command: 

STOP  <l«e>  [<vhich>] 

This  happens  automatically  when  the  current  task  is  suspended. 

Returning  Duka 

Tasks  which  have  been  STOPped  can  be  restarted  using  the  command: 

RESUME  <Imo>  [<*hich>] 

Note  that  it  is  also  acceptable  to  reSPiVI  a  task  which  was  suspended,  to  start  its 
execution  in  the  context  of  a  different  unit. 

Deleting  Tkaka 

Tasks  which  were  SPAHIed  can  be  deleted  using  the  command: 

DELETE  <laae>  [<ehich>] 

This  happens  automatically  when  the  current  task  ends. 

Stopping  Tank  Frames 

Task  frames  which  were  SPAHIed  can  be  stopped  using  the  command: 

STOP  <laae>  [<which>] 

Cheeking  if  a  Taak  is  Finished 

Tasks  which  have  been  spawned  can  be  tested  for  completion  as  follows: 
if  ( 

FIIISHED  <Issm>  [<which>] 

) 

The  FIIISHED  call  translates  to  a  single  function  call,  so  it  may  be  combined  with  other 
logical  operators  in  the  conditional.  For  example: 

if  ( 

FIIISHED  Go.Across .Bridge  0 

Ik 

FIIISHED  Go.Acrose.Bridge  1 

) 

SPAHH  unit. 3  Go.Across.Bridge  2 

Self-Destructing  Frames 

Some  reactive  tasks  create  task  frames  which  self-destruct  (the  spawned  frame  contains 
a  task  which  pops  the  frame,  and  the  frame  was  created  with  the  destroy  option).  In 
these  cases,  the  task  will  need  to  dear  out  any  references  it  has  kept  to  the  task  frame 
after  spawning.  The  following  command  can  be  used  by  a  task  to  dear  these  references. 

CLEAR  <laM>  [<which>] 

For  example,  a  version  of  the  commit  task  would  wait  for  a  target  which  meets  the 
commit  criteria,  then  react  by  pushing  an  opaque  frame  which  performed  an  intercept. 
The  task  had  no  reason  to  save  the  references  to  the  spawned  frame,  so  it  cleared  them 
right  away  (to  avoid  having  references  to  a  destroyed  object,  later). 
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evaluating 
*  tick 

if  (tgt_«eets_coawit_criteria(vehicle_id,  private)) 

{ 

aet.vaaaaaa_fire_at.vill ( vehide.id ,  private , 

par  amt  era) ; 

SPAWI  SELF  Air.To.Air.Intercept 
CLEAR  Air.To.Air.lntercept 

> 

param 

set.vassess.paraas (vehide.id ,  private , 

par  amt  era) ; 


2.8  Start  Body 


Next  comes  a  code  fragment  which  starts  the  task  (see  Chapter  1  [Overview],  page  1).  The  start 
body  should  perform  any  bookkeeping  (such  as  initializing  private  variables),  and  should  ensure 
that  the  task  transitions  into  an  acceptable  state. 


In  the  case  of  resuming  a  task,  any  subtasks  which  were  created  by  this  task  will  have  been 
suspended  when  this  task  was  suspended.  Thus,  it  is  important  for  the  start  body  to  either 
RESUME  or  reSPAHI  the  tasks  in  the  start  body.  In  general,  it  is  better  to  reSPAHI  the  task,  since 
the  composition  of  a  unit  or  the  parameters  of  the  task  may  have  changed  while  the  task  was 
suspended. 


For  example,  this  is  the  start  body  of  a  version  of  the  unit-level  follow  route  task: 


START 

f 

save.route. id (private,  task. entry); 

•vitch  (state->state) 

{ 

case  takingoff: 
case  folloving.route: 
case  at .end.of. route: 

break; 
case  ended: 
default: 

if  (vflvrte_able_to_follosroute( vehicle. id , 

private->ctdb) ) 

{ 
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SPAW  SELF  Vehicle.Follow.Route 
SPAW  SELF  Vahicle.Search 

if  (paraaeters->aove.type  ■■  VFLHRTE.M0VE.C0IT0UR) 
SPAW  SELF  Vehicle. Fly. Contour 
'following.route;  In  the  air 

> 

else 

< 

SPAW  SELF  Vahicle.Take.Qff 
‘takingoff;  lead  to  take  off 

> 

> 


First,  the  machine  saves  the  route  ID  in  its  private  variables,  so  that  it  will  be  able  to  distinguish 
route  changes  from  other  parameter  changes. 


Next,  it  looks  at  the  initial  state.  If  the  machine  is  already  in  a  running  state,  such  as  after  a 
migration  occurs,  the  software  does  not  need  to  do  anything  special  (in  this  case).  If  the  machine 
is  not  running,  the  software  spawns  some  tasks  and  transitions  to  its  first  state,  depending  upon 
the  current  conditions. 


2.9  State  Definitions 


Next,  the  state  machine  describes  each  state.  Each  description  is  organized  as  follows: 


« 


estate  naae> 
*  tick 


« 


< 


< 


code  fragment 

parans 

code  fragment 

<other  event> 
code  fragnent 

< other  event > 
code  fragnent 


Each  code  fragment  is  run  when  in  the  specified  state  during  the  corresponding  event. 
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2.10  End  Body 

The  end  body  is  a  code  fragment  which  runs  whenever  the  task  ends.  A  task  can  end  with  a 
transition  to  END: 


“EMD 


or  it  can  end  because  it  was  in  a  frame  which  was  popped.  In  either  case,  the  end  body  executes. 
Tasks  in  reactive  frames  can  cause  the  frame  in  which  they  reside  to  be  popped  when  they  end  (the 
self-destruct  behavior  described  above)  using  the  command: 

POP.OVV.TASKFIUME 

in  their  end  body. 

The  general  form  of  the  end  body  is: 


END 

i 

code  fragment 

The  generated  software  automatically  destroys  any  spawned  tasks  (but  not  spawned  task  frames) 
when  a  task  is  ended. 


2.11  Suspend  Body 

The  optional  suspend  body  is  a  code  fragment  which  runs  whenever  the  task  is  suspended.  A 
task  is  suspended  when  an  opaque  frame  is  pushed  on  top  of  its  frame,  or  when  it  is  temporarily 
removed  from  a  background  frame. 

The  general  form  of  the  suspend  body  is: 


SUSPEND 

t 


code  t regnant 
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The  generated  software  automatically  suspends  any  spawned  tasks  (but  not  spawned  task 
frames)  when  a  task  is  suspended. 
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S  Functions 


The  following  sections  describe  each  function  provided  by  libtask,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


3.1  tnsk-init 


void  task.initO 


task.init  initializes  libtask.  Call  this  before  calling  any  other  libtask  functions  or  any  specific 
task  initializations. 


3.2  task-register 


void  task.register (saf .nodel_nunber ,  parana ,  predicate, 

start,  tick,  end,  suspend,  state. size, 
n.bef ore ,  before,  n_ after,  after) 
uint32  saf  .SK>del_nunber ; 

void  (*parans) () ; 

int32  (^predicate) ( ) ; 
void  (*start) () ; 

void  (*tick)(); 
void  (vend) () ; 
void  (*suspend)  () ; 
uint32  st at e.s ize ; 

int32  n.bef ore; 

uint32  before  □; 

int32  n. after; 

uint32  after  □ ; 


‘saf .aodel.nunber’ 

Specifies  the  SAF  model  implemented  by  the  task  (from  ‘p.safnodels.h’) 
‘parens’  Specifies  the  function  to  call  when  task  parameters  change 
‘predicate’ 

Specifies  the  function  to  call  for  enabling  tasks 
‘start*  Specifies  the  function  to  call  to  start  the  task 

‘tick’  Specifies  the  function  to  call  each  tick 

‘end’  Specifies  the  function  to  call  if  the  task  must  be  stopped 
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‘suspend’  Specifies  the  function  to  call  if  the  task  is  suspended  (start  will  be  invoked  before  the 
next  tick) 

‘stats.size’ 

Specifies  the  size  of  the  task  state  data 

‘n.before’ 

Specifies  how  many  task  are  in  the  before  list 

‘before  □’ 

Specifies  the  list  of  tasks  which  must  be  executed  before  this  one 
‘n_ after’  Specifies  how  many  task  are  in  the  after  list 
‘afterO’  Specifies  the  list  of  tasks  which  must  be  executed  after  this  one 

task.register  registers  a  task  with  libtask  so  that  it  may  be  executed  later.  Note  that  any  of 
the  functions  may  be  passed  as  MULL.  The  predicate  function  for  tasks  which  are  not  just  enabling 
tasks  should  return  whether  they  are  in  the  ended  state.  This  way,  a  subsequent  task  frame  may 
refer  to  an  executing  task  as  its  enabling  task,  to  trigger  a  transition  when  the  task  completes. 

Note  that  specifying  before  and  after  tasks  does  not  guarantee  that  those  tasks  will  be  exe¬ 
cuting  —  it  merely  ensures  that  if  those  tasks  are  executing,  they’re  execution  will  happen  at  the 
right  time  relative  to  this  task. 


3.3  task.get_8tate 

ADDRESS  task.get.stata (db ,  task. id) 

PO. DATABASE  *db; 

Object ID  etask.id; 

‘db’  Specifies  the  PO  database 

‘task.id’  Specifies  the  task’s  PO  ObjectID 

task_get_atate  finds  state  variables  associated  with  a  task  (performs  a  sequence  of 
po.get.object  calls,  and  error  checking). 


3.4  taak-spawn-subtask 

void  task.spawn.subtaskftask.entry,  unit.or_fraae.id,  spawn. task, 

spawn. ini t,  spawn. id) 


f 
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P0.DB.E1TRY 
Object ID 
TaskClass 

▼old 
Object ID 


*task. entry; 

♦unit  _or_f raas. id ; 
•■pawn. teak; 
(*spawn_init)(); 
♦spawn.id; 


‘taak.entry’ 

Specifies  the  task  which  is  spawning  a  new  task 
‘unit.or.frane.id’ 

Specifies  either  the  unit  which  is  to  execute  the  task  (in  its  background  frame),  or  the 
frame  into  which  the  task  should  be  spawned 

*spavn.task’ 

Specifies  the  body  of  the  task  which  will  be  spawned 
‘spawn,  init’ 

Specifies  a  function  to  call  to  initialize  the  task's  state 

‘spawn.id’ 

Specifies/Returns  the  Object  ID  of  the  spawned  task 

task.spawn.subtask  starts  a  task  in  the  specified  frame  (or  if  the  unit.or_fraM.id  is  that 
of  a  unit,  then  in  that  unit’s  background  frame).  If  spawn.id  already  contains  the  Object  ID  of 
an  existing  task,  that  task  will  be  reused.  Otherwise  a  new  task  will  be  created  and  its  ID  will  be 
returned  in  spawn_id. 

The  caller  should  fill  in  the  nodal,  ref  count,  size,  and  data  parts  of  the  task.  The  spawn,  init 
function  will  be  called  to  fill  in  the  refcount,  size,  and  data  of  the  created  (or  reused)  stats 
object.  This  function  should  be  prototyped  as  follows: 

void  spawn. init (task,  stats) 

TaskClass  *task; 

TaskStatsClass  *stats; 


\ 

'< 


i 


For  example,  the  init  function  used  by  the  vehicle-level  route  following  task,  might  look  like  this: 
/•ARGSUSED*/ 

void  vflwrts_init.task_stats(task,  stats) 

TaskClass  *task; 

TaskStatsClass  estate ; 

state->size  ■  size of (VFLWRTE.STATE) ; 
stats* >rsf count  ■  0; 

bzsro (state->data ,  sizeof (VFLWRTE.STATE) ) ; 


20 


LibTask  Programmer’s  Guide 


3.5  task.subtask-parameters 


int32  task.subtask 
PO.DB.EiTRY 
ObjectID 
ADDRESS 


.parameters (task. entry,  spawn. id,  pari 
*■ task,  entry; 

•spare,  id; 

•paraas; 


) 


’task,  entry’ 

Specifies  the  task  which  spawned  the  subtask 

‘spara.id’ 

Specifies  the  Object  ID  of  the  spawned  subtask 
‘paraas’  Returns  the  parameter  values  of  the  subtask 

task_subtask_paraaaters  gets  the  current  parameters  used  by  a  spawned  task.  This  is  used 
by  the  ‘f  sa2ch’  code  generator  to  provide  initial  values  for  parameters  when  a  subtask  is  updated. 


3.0  task-update_Bubtask 


void  task.update.subtask (task. entry,  apara.task,  spawn. id) 
PO.DB.EITRY  *task_ retry; 

•spare. task; 


TaskClass 

Obi act ID 


mafiaafi  A  A  « 


‘task.retry’ 

Specifies  the  task  which  spawned  the  subtask 
‘spare.task’ 

Specifies  the  new  task  parameters 

‘spare,  id’ 

Specifies  the  Object  ID  of  the  spawned  subtask 


task.update.subtask  updates  the  parameters  of  a  spawned  task. 


3.7  task.suspend_Bubtask 


void  task.suspred.subtaskCtask.antry,  spawn. id) 
PO.DB.EITRY  *task.retry; 

ObjectID  *spare.id; 
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‘tank,  entry’ 

Specifies  the  task  which  spawned  the  subtask 

‘spam,  id’ 

Specifies  the  Object  ID  of  the  spawned  subtask 
task_suspend_eubtask  suspends  execution  of  a  spawned  task  by  setting  its  suspended  flag. 


3.8  task_re8ume-subtask 

▼old  task.resune.subtask(taak. entry,  spawn. id) 

PO.DB.EMTRY  *t ask. entry; 

Object  ID  *  spam,  id; 

‘task. entry’ 

Specifies  the  task  which  spawned  the  subtask 

‘spam_id’ 

Specifies  the  Object  ID  of  the  spawned  subtask 
t ask. resuae.  subtask  resumes  execution  of  a  spawned  task  by  clearing  its  suspended  flag. 


3.9  task-delete-subtask 


▼oid  task.delete.  subtask  (task,  entry,  spam.id) 
PO.DB.EITRY  *t ask. entry; 

ObjectID  *spam_id; 


‘task,  entry’ 

Specifies  the  task  which  spawned  the  subtask 

‘spam,  id’ 

Specifies  the  Object  ID  of  the  spawned  subtask 


task.delete.subtask  deletes  a  task  spawned  with  task.spara.subtask,  and  zero’s  out  the 
passed  spam.id. 
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S.10  task_stop-subframe 

▼old  task.stop.subfrane (task.entry,  spawn. id) 

PO.DB.EMTRY  *taak_antry ; 

Object ID  * spawn. id; 

‘teak. entry' 

Specifies  the  task  which  spawned  the  subframe 

'spawn,  id’ 

Specifies  the  Object  ID  of  the  spawned  subframe 
task.stop.subfraM  stops  a  spawned  frame  by  clearing  out  its  unit  field. 


S.ll  taak.get.db 

PO.DATABASE  *task_get_db (task. entry) 
PO.DB.EVTRY  *t ask. entry; 


'task.entry’ 

Specifies  the  task 


taak_get_db  gets  the  PO  database  in  which  a  task  resides  (for  use  by  ‘f  sa2ch’  code  generator). 


3.12  task.get.uiiit 

PO.DB.EMTRY  *task_get .unit  (task.entry) 

P0.DB.EITRY  *t ask. entry ; 

'task.entry’ 

Specifies  the  task 

task.get.unit  gets  the  unit  which  is  executing  a  task  (for  use  bv  ‘fsa2ch’  code  generator). 
Note  that  this  function  will  not  work  for  enabling  tasks,  since  mult  its  can  be  executing  a 
single  enabling  task  (TOLL  will  be  returned). 
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S.1S  tnak-jcomplete 

int32  task. complete (task. entry,  spawn. id) 

PO_DB_EIT!tY  etask.entry; 

Object ID  *spasn_id; 

‘task.entry’ 

Specifies  the  task  which  spawned  the  subtask 

‘spawn.id’ 

Specifies  the  Object  ID  of  the  task  being  queried 

task. complete  calls  the  registered  predicate  function  for  a  spawned  subtask,  and  returns  the 
result. 


S.14  task_pop_ownframe 

▼old  task.pop.ownf  me  (task,  entry) 

PO.DB.EITRY  *t ask. entry; 

‘task.entry’ 

Specifies  a  task  in  the  frame 

task_pop.ounfrane  unassigns  the  task  -uaf  n  which  the  passed  task  resides. 


3.15  task-classJnit 

Told  task.clasa.init (parent. class) 

CLASS.PTR  parent. class ; 

‘parent. class’ 

Class  of  the  parent  (declared  with  dass.declare.class,  such  as  C2obj  class) 

task.clasa.init  creates  a  handle  for  attaching  task  class  information  to  entries.  The  parent.dass 
is  one  created  with  dass.declare.class. 
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S.16  task_create 

void  taak.createC entry,  db) 

PO.DB.EITRY  * entry; 

PO.DATABASE  *db; 

‘entry’  Specifies  the  task’s  entry  in  the  PO  database 
‘db’  Specifies  the  PO  database 

task. create  creates  the  task  class  information  for  a  entry  and  attaches  it  to  the  entry’s  libdass 
user  data. 


3.17  task^destroy 

void  task.deetroy (entry) 

PO.DB.EITRT  * entry; 

‘entry’  Specifies  the  task  entry 

task.destroy  frees  the  task  class  information  for  a  entry. 


3.18  task_iexec 

void  task.ezec (entry,  vehicle. id) 

PO.DB.EITRT  * entry; 
int32  vehicle. id; 

‘entry’  Specifies  the  task  entry 
‘vehicle. id’ 

Specifies  the  ID  of  the  vehicle  which  is  to  execute  the  task 

task.exec  executes  the  task  associated  with  the  passed  entry  in  the  context  of  the  passed 
vehicle.  Note  that  it  is  not  safe  to  execute  the  same  task  entry  on  more  than  one  vehicle,  since 
their  state  may  diverge. 
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3.19  task-predicate 


int32  task.predicate(entry,  vehicle,  id.  current .opaque. task.fraae , 

next _t eek.fr eae ,  nua_executing_tasks ,  executing. tasks) 
P0.DB.EHRY  ‘entry; 
int32  vehicle. id; 

P0.DB.EURY  *  current. opeque.teek.freae ; 

P0.DB.EHRY  ‘next .teek.f reae ; 
int32  nua.execut ing. tasks ; 

P0.DB.EHRY  *executing_tasksO ; 


‘entry’  Specifies  the  task  entry 
‘vehicle.id’ 

Specifies  the  ID  of  the  vehicle  which  is  to  execute  the  predicate 

‘current .opaque.task.fraae’ 

Specifies  the  exectuing  opaque  task  frame  in  current  context 

‘next.task.fraae’ 

Specifies  the  frame  containing  the  enabling  task 
‘nua.exectuing.tasks’ 

Specifies  the  number  of  executing  tasks  in  current  context 
*exectuing_t  asks ’ 

Specifies  the  list  of  exectuing  tasks  in  current  context 

task.predicate  runs  the  predicate  function  associated  with  the  task  in  the  context  of  the 
passed  vehicle,  and  returns  its  result.  If  no  predicate  exists  for  the  task,  0  will  be  returned. 


3.20  task-stop 


void  task. stop (entry,  vehicle.id) 
P0.DB.EnRY  *  entry; 
int32  vehicle.id; 


‘entry’  Specifies  the  task  entry 
‘vehicle.id’ 

Specifies  the  ID  of  the  vehicle  which  is  running  the  task 

task.stop  stops  the  execution  of  the  task  in  the  context  of  the  passed  vehicle.  This  typically 
is  done  when  a  task  frame  is  popped. 
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3.21  tukjuapend 


void  taak.suspendfentry ,  vehicle. id) 
PO.DB.EHRY  * entry; 
int32  vohido.id; 


‘entry’  Specifies  the  task  entry 
‘vehicle. id’ 

Specifies  the  ID  of  the  vehicle  which  is  running  the  task 

task_suspand  suspends  the  execution  of  the  task  in  the  context  of  the  passed  vehicle.  This 
typically  is  done  when  a  task  frame  pushed  on  top  of  another  frame.  The  next  time  taak.exec  is 
called  for  this  task/vehicle,  the  task  will  be  restarted. 


3.22  task-stop Jf_suspended 

void  ta8k.stop.if_susp«nded(eatry) 

P0_DB_E*TRY  * entry; 

‘entry’  Specifies  the  task 

tank.etop.if  .suspended  sets  a  flag  in  the  task  indicating  that  if  the  task  management  software 
concludes  that  the  task  has  been  suspended,  then  the  task  should  be  stopped  (see  tagr.t  ick .  c :  stop.taskf  r 
for  details). 


3.23  task.parains 

void  task.paraas(entry) 

PO.DB.ERTRY  * entry; 

‘entry’  Specifies  the  task 

task.paraas  triggers  a  paraas  event  for  this  task  prior  to  the  next  tick,  and  marks  the  task  as 
RUVRIIG.  This  is  used  by  the  task  management  software  when  task  parameters  are  overridden  in  a 
transparent  frame. 
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3.24  tank-migrated 

void  taak_nigrated(entry) 

PO.DB.EITRY  * entry; 

‘entry’  Specific*  the  task  entry 

taekjd.gr ated  clean  local  task  execution  state.  This  is  typically  done  when  a  vehicle  migrates 
to  another  simulation  host. 


3.25  task-get-sequence 

int32  taek.get. sequence (entry) 

PO.DB.EITRY  *  entry ; 

'entry'  Specifies  the  task  entry 

tank.gat.aequonce  returns  the  sequence  number  associated  with  the  passed  task.  The  sequence 
numbers  of  tasks  imply  an  order  of  execution,  with  lower  numbers  executing  before  higher  ones. 
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1  Overview 


LibTaskEdit  implements  the  SAF  task  frame  and  task  editors.  Individual  tasks  which  can 
be  assigned  from  the  user  interface  register  their  unique  editors  with  libTaskEdit,  which  then 
automatically  incorporates  them  into  the  user  interface.  Definition  of  a  task  editor  requires  three 
things: 

•  Creating  a  file  which  defines  a  libEditor  editor  which  corresponds  to  the  public  PARAMETERS 
part  of  the  task  shared  data. 

•  Registering  the  name  of  this  data  file,  as  well  as  other  information  about  the  task  with  lib¬ 
TaskEdit. 

•  Defining  the  default  initialization  to  be  used  in  each  task  frame  which  is  to  contain  the  task. 
See  (undefined)  [Examples],  page  (undefined). 
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2  U  sage 


The  software  library  ‘libtaskedit.a’  should  be  built  and  installed  in  the  directory 
‘/co— on/lib/’.  You  will  also  need  the  header  file  ‘libtaskedit.h’  which  should  be  installed  in 
the  directory  ‘/co— on/include/libinc/’.  If  these  files  are  not  installed,  you  need  to  do  a  ‘make’ 
in  the  libtaskedit  source  directory.  If  these  files  are  already  built,  you  can  skip  the  section  on 
building  libtaskedit. 


2.1  Building  Libtaskedit 

The  libtaskedit  source  files  are  found  in  the  directory  7co— on/libsrc/libtaskedit’.  ‘RCS’ 
format  versions  of  the  files  can  be  found  in  ‘/nfs/ca— on.src/libsrc/libtaskedit’. 

If  the  directory  ‘co— on/libarc/libtaskedit*  does  not  exist  on  your  machine,  you  should  use 
the  ‘geabuild’  command  to  update  the  common  directory  hierarchy. 

To  build  and  install  the  library,  do  the  following: 

•  cd  co— aa/libsrc/llbtaahedit 

•  co  RCS/*,v 

•  sake  install 

This  should  compile  the  library  ‘libtaskedit.a’  and  install  it  and  the  header  file 
‘libtaskedit  .h’  in  the  standard  directories.  If  any  errors  occur  during  compilation,  you  may  need 
to  adjust  the  source  code  or  ‘Makefile’  for  the  platform  on  which  you  are  compiling,  libtaskedit 
should  compile  without  errors  on  the  following  platforms: 

•  Mips 

•  SGI  Indigo 

•  Sun  Sparc 


2.2  Linking  with  Libtaskedit 

Libtaskedit  can  be  linked  into  an  application  program  with  the  following  link  time  flags:  ‘Id 
[source  .o  files]  -L/co— on/lib  -ltaskedit  [other  libraries]’.  If  your  compiler  does  not 
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support  ‘-L’  syntax,  you  can  use  the  archive  explicitly:  ‘Id  [source  .o  files] 
/coMaon/lib/libtaakodit .  a’. 


Libtaskedit  depends  directly  on  the  following  libraries:  libsafgui,  libtactmap,  libcoordi nates, 
libsensitive,  libcallback,  libpo,  libeditor,  libselect,  libreader,  libgraphics,  and  libprivilege. 


2.S  Examples 


The  following  are  code  fragments  from  an  early  version  of  the  task  libubingofuel  (Unit  Bingo 
Fuel),  which  demonstrate  how  to  define  an  editable  task. 


The  parameters  are  defined  in  the  standard  fashion: 


typsdef  struct  ubfuel.paraaaters 

i 

Object ID  base; 

uintlG  .padding; 

float64  speed; 

floated  alt itude ; 

>  UBIIGOFUEL.PARAMETERS ; 


The  data  file  (‘ubfuel.rdr’)  defines  the  editor  for  this  data  structure: 


((naae  "Bingo  Fuel") 

(struct  (base  intie  3) 

(padding  16) 

(speed  floated) 

(altitude  floated) 

) 

(editor  ("Refuel  Point"  OBJECT  base  ROCAICEL 
objectClassPoint  objectClassText) 

("Speed"  SPEED  speed) 

("Altitude”  ALTITUDE  altitude) 

) 

(initial  (base  FORCE) 

(speed  COISTAIT  250.0) 

(altitude  COBSTAVT  3000.0) 

) 

(render  REVERT) 

) 


Note  that  for  tasks  which  are  not  enabling  tasks,  most  of  the  initial  parameters  will  never  be 
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used,  since  they  will  come  in  the  task  frame  definition. 


Also  note,  that  the  render  list  for  the  task  should  read  (render  REVERT)  in  all  cases. 


The  intialization  methods  are  declared  again  for  each  task  frame  (note  that  initializations  which 
do  not  differ  between  task  frames  need  not  be  repeated): 


(... 

("Sweep" 

(SM.UBingoFuel  BOTH 

(baae  FORCE  "You  auet  specify  a  refuel  point") 
(speed  COISTAIT  164.622) 

(altitude  COISTAIT  6096.0) 

) 

•  •  • 

) 

•  •  e 

) 


Finally,  to  register  the  task  with  libTaskEdit,  the  library  calls  the  following  from  its  global 
<task>.init  function: 


void  uflwrte.initO 


taskedit .register (SM.UBingoFuel ,  "ubf uel . rdr" , 

sizeof(UBHGOFUEL. PARAMETERS) , 
ubf uel. init. task. state) ; 

> 


The  initialization  function  for  libubfuel  is  defined  as  follows: 


void  ubfuel.init.task.state(task„  state) 

TaskClass  *task; 

TaskStateClass  estate; 

{ 

state- >size  ■  sizeof (UBIMGOFUEL.STATE) ; 
state->ref count  -  UBIIGOFUEL.STATE.REFEREICES ; 
bzero(state->data ,  sizeof (UBIMGOFUEL.STATE) ) ; 

> 


The  task  is  provided  in  case  task  parameters  are  needed  in  order  to  initialize  the  state  (generally 
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not  the  case).  The  refcount  should  be  set  to  the  number  of  Object  ID  references  which  appear  in 
the  state  structure. 
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3  Functions 

The  following  sections  describe  each  function  provided  by  libtaskedit,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 

3.1  taskeditJnit 

void  taskedit.initO 

taskedit.init  initializes  libtaskedit.  Call  this  before  any  other  libtaskedit  function. 


S.2  tasked  it _in  it  _gui 


int32  taskedit_init.gui(taskfranes_file,  data.path,  reader.f lags , 

dialog.parent , 

gui,  tactnap,  tcc,  aap.erase.gc , 
sensitive,  select,  ref rash, event ,  db) 
*taskf ranes.f ile ; 

♦data.path; 
reader.f lags ; 
dialog.parent ; 
gui; 

tactaap; 
tcc; 

aap.erase.gc; 
sensitive; 
select; 


char 

char 

uint32 

Widget 

SGUI.PTR 

TACTKAP.PTR 

COORD. TCC.PTR 


GC 

SMSTVE.WIIDOW.PTR 
SELECT.T00L.PTR 
CiLLBACK.EVEIT.PTR  ref resh.event ; 
PO.DATABASE  *db; 


‘taskfraaes.file* 

Specifies  the  name  of  the  file  with  taskframe  definitions 

‘data.path’ 

Specifies  the  directory  where  data  files  are  expected 
‘reader  .flags’ 

Specifies  flags  to  be  passed  to  reader.read  when  reading  data  files 
‘dialog.parent’ 

Specifies  top-level  shell  which  should  parent  popup  dialogs 
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‘gui’  Specifies  the  SAF  GUI 

‘tactnap’  Specifies  the  tactical  map 

‘tcc’  Specifies  the  map  coordinate  system 

‘nap.erase.gc’ 

Specifies  the  GC  which  can  erase  things  from  the  tactical  map 

‘sensitive’ 

Specifies  the  sensitive  window  for  the  tactical  map 
‘select’  Specifies  the  selection  tool 
‘refresh.event’ 

Specifies  the  event  which  fires  when  the  map  is  refreshed 
‘db’  Specifies  the  persistent  object  database 

taskedit.init.gui  creates  the  task  frame  editor.  Individual  task  editors  are  also  created  at 
this  time,  so  be  sure  to  initialize  the  task  libraries  before  calling  this  function  (so  they  can  register 
their  editors).  The  data.path  and  reader  .flags  are  used  when  reading  the  individual  task  editor 
definitions.  Note  that  this  registers  an  association  with  libgraphics,  so  it  must  be  called  after 
grph. create. editors.  A  non-zero  return  value  indicates  an  error  occurred. 


3.S  taskedit .register 

void  taskedit .register (saf .nodal,  data.file,  sizeof .struct,  init.fcn) 
uint32  saf_nodel; 

char  *data.file; 

uint32  sizeof. struct; 

TASIEDIT.IlIT.FUICnOI  init.fcn; 

‘saf .nodal’ 

Specifies  the  SAF  model  of  the  task 

‘data.file’ 

Specifies  the  name  of  the  data  file  where  the  task’s  editor  is  defined 
'sizeof  .struct' 

Specifies  the  size  of  the  task  parameter  data  structure 

‘init.fcn’ 

Specifies  the  function  to  call  to  initialize  task  state 

taskedit.register  registers  a  task  editor  with  libtaskedit.  The  caller  provides  the  name  of  a 
data  file,  which  libtaskedit  will  read  when  (if)  the  GUI  is  initialized.  The  sizeof  .struct  specifies 
the  size  of  the  public  parameters  of  the  task  (<task>.PARA!lETERS). 
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The  init.fcn  is  responsible  for  initializing  the  state  of  the  task.  The  function  must  set  the 
size,  ref  count,  references,  and  data  portions  of  the  state.  The  task  will  already  be  filled  in  by 
libtaskedit,  and  should  not  be  modified;  it  is  supplied  only  to  provide  context  for  initialization. 

Note  that  the  init.fcn  may  be  called  more  than  once  (such  as  when  a  mission  is  reused),  so 
the  refcount  field  of  the  task  should  be  set  to  an  explicit  value  (number  of  parameter  references 
plus  number  of  state  references),  rather  than  being  incremented  by  the  number  of  state  variables. 
For  example, 

statevars->ref count  ■  UFLWRTE.STATE.REFEREICES ; 
is  an  appropriate  expression,  but 

statevars->ref count  UFLVRTE.STATE.REFERESCES; 


is  not. 


The  init.f cn  should  be  prototyped  as  follows: 


void  init .function (task,  state) 
TaakClass  *task; 

TaskStateClass  estate; 


3.4  tnskedit^ndd^enabling 

void  taskedit.add_enabling(saf  jeodel) 
uint32  saf  jeodel ; 

‘saf  .nodal’ 

Specifies  the  SAF  model  of  the  enabling  task 

taskedit.add.anabling  notifies  libtaskedit  that  a  task  should  be  treated  as  an  enabling  task. 
The  editor  registered  with  this  task  in  a  previous  call  to  taskedit.register  will  be  added  to  this 
list  of  editors  available  in  when  the  task  editor  is  run  in  enabling  task  mode. 


3.5  taskedit-reinit 
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▼old  tasksdit_rsinit(db,  taakfraae) 

PO. DATABASE  *db; 

PO.DB.EVTRY  *tukfrm ; 

‘db’  Specifies  the  persistent  object  database 

‘taakfraae’ 

Specifies  the  task  frame  to  reinitialize 

taskedlt.relnit  calls  the  registered  initialization  function  for  all  the  tasks  in  a  task  frame. 
This  is  provided  to  allow  reuse  of  missions  (the  tasks  in  a  mission  start  out  initialized,  but  once 
they  have  beat  used,  they  may  not  be  in  an  acceptable  state  for  reuse). 


S.6  taskedit_get_editor 

TASKEDIT.GUI.PTR  t aakedit .get .editor (gul) 

SGUI.PTR  gui; 

‘gui’  Specifies  the  SAF  GUI 

taakedit_get. editor  finds  a  taskframe  editor  created  for  the  passed  GUI.  Returns  NULL  if 
none  exists. 


3.7  tanked it.joverride 

void  taskedit. override (editor,  unit.id) 

TASKEDIT.GUI.PTR  editor; 

Object ID  eunit.id; 

‘editor*  Specifies  the  task  frame  editor 

‘unit.id’  Specifies  the  unit  whos  tasks  are  to  be  modified 

tankodit.override  invokes  the  task  editor  in  override  mode.  The  editor  allows  modification  of 
those  tasks  which  exist  in  current  frames  being  executed  by  the  passed  unit.  Any  modifications  are 
placed  in  a  transparent  frame.  The  unit  is  monitored  for  changes  in  its  task  frames,  which  might 
cause  the  set  of  modifiable  tasks  to  change. 
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3.8  taskedit_start_editor 

void  taakodit.atart .editor (editor,  destrojVbenDone ,  unit. type, 

fraae.id) 

TASKED IT. GUI _PTR  editor; 
uint32  destroy VhenDone ; 

Ob j  ectType  unit .type ; 

ObjectID  *f rase. id; 

‘editor’  Specifies  the  task  frame  editor 
‘destroyHhenDone* 

Specifies  the  value  of  the  created  frames’  destroyUhenDone  field 

‘unit  .type’ 

Specifies  the  type  of  unit  (if  non-zero,  only  allowed  task  frames  for  that  unit  type  will 
be  sensitive) 

‘fraae.id’ 

Specifies  the  address  into  which  the  frame  should  be  placed 

tankedit.start.editor  invokes  the  task  editor  in  normal  mode.  When  the  editor  is  exited, 
the  ObjoctID  of  the  created  frame  will  be  placed  into  the  address  passed  as  fraae.id.  Thus,  this 
must  be  non-volatile  memory  space. 


3.9  taakedit.start.jetask.editor 

void  taskedit_start_etask_editor(editor,  taak.id) 

TASKEDIT.GUI.PTR  editor; 

ObjoctID  * task .id; 

‘editor*  Specifies  the  task  frame  editor 

‘task,  id*  Specifies  the  address  into  which  the  task  should  be  placed 

taskedit.start.etask.editor  invokes  the  task  editor  in  enabling-task  mode.  When  the  editor 
is  exited,  the  ObjectID  of  the  created  task  will  be  placed  into  the  address  passed  as  task.id.  Thus, 
this  must  be  non-volatile  memory  space. 
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4  Add  in  g  Help 


It  may  be  the  case  that  some  of  the  fields  which  make  up  an  editor  will  need  explanation  at  run 
time.  Whereas  forced  choices  require  that  a  special  help  message  be  provided,  most  editable  fields 
will  just  get  the  default  help  message  provided  by  libeditor. 

In  some  cases,  this  is  acceptable.  For  example,  the  altitude  parameter  of  a  follow  route  mission  is 
self  explanatory.  However,  in  cases  where  additional  help  is  needed,  there  is  a  facility  to  add  this  help 
through  the  X  resource  database  (see  section  ‘X  Resource  Definitions'  in  LibEditor  Programmer’s 
Manual). 

To  add  context-specific  help,  a  task  library  should  do  the  following: 

1.  Create  an  X  resource  file  (‘<tasknaae>  .xrdb’)  in  the  task  library  with  the  special  help  in  it. 
The  resource  lines  should  read: 

*.SAFGUI.«. Editor.*. Task  Name . * . Field  Name.*. Help:  Help  String 

For  example,  to  add  a  description  to  the  Radar  Orientation  Aziauth  field  of  the  Targeting 
task  editor,  the  resource  might  appear  as  follows: 

e.SAFGUI. '.Editor. '.Targeting.*. Radar  Orientation  Aziniuth.*.Help:  \ 
Specifies  the  desired  aziauth  of  the  center  of  the  radar  \ 
voluae  (0  is  interpreted  as  down  the  Y-axis  of  the  vehicle  \ 
and  is  positive  counter-clockwise) . 

2.  Add  the  '.xrdb'  file  to  the  READERS  list  in  the  library  ‘Makefile’. 

3.  Add  a  line  to  the  top  level  resource  file  ‘src/ModSAF/HodSAF’  to  include  this  new  resource  file. 
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1  O  verview 


Libtaskframe  provides  simulation  support  for  task  frames.  It  provides  functions  which  may  be 
called  to  determine  what  task  frames  come  after  a  given  frame  (in  the  context  of  a  mission),  what 
tasks  belong  to  a  task  frame,  and  whether  the  enabling  tasks  in  a  task  frame  indicate  it  should  be 
triggered. 

The  call  to  test  enabling  tasks  (taskfr.check.  enabling)  uses  the  following  algorithm: 

1.  Run  the  predicate  function  for  each  enabling  task,  to  get  its  True/False  value. 

2.  Get  the  first  item  off  the  logic  stack. 

3.  Act  on  the  current  item: 

Task  number 

Push  the  value  True/False  value  for  that  task  from  step  1  onto  the  evaluation 
stack. 

NOT  operator 

Complement  the  value  on  the  top  of  the  evaluation  stack. 

AND,  OR  operators 

Pop  the  top  off  the  evaluation  stack  and  logically  combine  it  with  the  value  on  the 
new  top  of  the  evaluation  stack. 

STOP  operator 

Return  the  value  on  the  top  of  the  evaluation  stack. 

4.  Get  the  next  value  off  the  lope  stack  and  go  to  step  3. 

The  check-enabling  algorithm  returns  False  if  the  stack  underflows. 

The  two  query  functions  (to  get  subsequent  frames,  and  to  get  tasks)  operate  by  querying  the 
persistent  object  database.  Although  it  is  possible  for  the  task  frame  to  keep  this  information 
up  to  date  by  monitoring  libPO  events,  it  was  implemented  with  queries  for  simplicity.  This 
implementation  should  be  monitored,  and  should  be  changed  if  the  cost  of  the  queries  is  too  high. 
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2  Usage 


The  software  library  ‘libt aaklraae .  a’  should  be  built  and  installed  in  the  directory 
‘/coanon/lib/’.  You  will  also  need  the  header  file  ‘libtaskfraae.h’  which  should  be  installed  in 
the  directory  7co«K>n/includa/libinc/’.  If  these  files  are  not  installed,  you  need  to  do  a  ‘aake’ 
in  the  libtaskframe  source  directory.  If  these  files  are  already  built,  you  can  skip  the  section  on 
building  libtaskframe. 


2.1  Building  Libtaskframe 

The  libtaskframe  source  files  are  found  in  the  directory  ‘/coaaon/libsrc/libtaskfraae’.  ‘RCS’ 
format  versions  of  the  files  can  be  found  in  ‘/nfs/ccMon.src/libsrc/llbtaakfraaa’. 

If  the  directory  ‘coaeon/libsrc/libtaskfraae’  does  not  exist  on  your  machine,  you  should  use 
the  ‘genbuild’  command  to  update  the  common  directory  hierarchy. 

To  build  and  install  the  library,  do  the  following: 

•  cd  c osmoa/llbsrc/llbt askf raae 

•  co  RCS/*,v 

•  aake  install 

This  should  compile  the  library  ‘libtaskfrsae.a’  and  install  it  and  the  header  file 
‘libtaskfraae.h’  in  the  standard  directories.  If  any  errors  occur  during  compilation,  you  may  need 
to  adjust  the  source  code  or  ‘Makefile’  for  the  platform  on  which  you  are  compiling,  libtaskframe 
should  compile  without  errors  on  the  following  platforms: 

•  Mips 

•  SGI  Indigo 

•  Sun  Sparc 


2.2  Linking  with  Libtaskframe 

Libtaskframe  can  be  linked  into  an  application  program  with  the  following  link  time  flags:  ‘Id 
[source  .o  files]  -L/coamn/lib  -It  askf  raae  [other  libraries]’.  If  your  compiler  does  not 
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support  ‘-L’  syntax,  you  can  use  the  archive  explicitly:  ‘Id  [source  .o  files] 
/cosMon/lib/libtaslcfrane .  s’. 

Libtaskframe  depends  on  libdass,  libpo,  and  libtask. 
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3  Functions 


The  following  sections  describe  each  function  provided  by  libtaskfr&me,  including  the  format 
and  meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


3.1  taskfrJnit 

▼old  taskfr.initO 

taskfr.lnlt  initializes  libtaskframe.  Call  this  before  calling  any  other  libtaskfr&me  functions 
or  any  specific  taskframe  initializations. 


3.2  taskfr^class Jnit 

▼old  taskfr.class.init (parent. class) 

CLASS.PTR  parent .class; 

‘parent.dass’ 

Specifies  the  parent  class  (such  as  C2obj  class) 

taskfr.class.init  creates  a  handle  for  attaching  taskframe  class  information  to  entries.  The 
parent. class  is  one  created  with  class  .declare .class. 


3.3  taskfr^create 

▼old  taskfr. create (entry,  db) 

PO.DB.EITRT  * entry; 

P0 .DATABASE  *db; 

‘entry’  Specifies  the  task  frame's  entry  in  the  PO  database 
‘db’  Specifies  the  PO  database 

taskfr.create  creates  the  taskframe  class  information  for  a  entry  and  attaches  it  to  the  en¬ 
try's  libdass  user  data.  This  function  will  not  attach  any  data  if  the  PO  object  class  is  not 
ob j  ectClassTaskPrane. 
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3.4  taskfr .destroy 

▼old  taakfr.destroy (entry) 

PO.DB.EITRY  * entry; 

‘entry’  Specifies  the  task  frame’s  entry  in  the  PO  database 
taskfr  .destroy  frees  the  taskframe  class  information  for  a  entry. 


3.5  taskfr-changed 

▼old  taskfr.changed(entry) 

PO.DB.EITRY  sentry; 

’entry’  Specifies  the  task  frame’s  entry  in  the  PO  database 

taskfr.changed  updates  the  taskframe  class  information  in  response  to  a  libpo  object  .changed 
event. 


3.6  taskfr -getjn  ext 

int32  taskfr.get.next (entry,  subsequent) 

PO.DB.EITRY  sentry; 

P0.DB.EITRY  s subsequent  □  ; 

’entry’  Specifies  the  task  frame 
‘subsequent’ 

Returns  a  list  of  subsequent  frames 

taskfr_gat_next  returns  a  list  of  task  frames  which  come  after  this  one.  The  return  value 
indicates  how  many  taskframea  were  returned. 


3.7  taskfr^checkjenabling 
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int32  taskfr. check. enabling (entry,  vehicle. id, 

current.opaque.task.f raae , 
nun.executing.tasks,  executing.tasks) 

P0.DB.QmY  *  entry; 
lnt32  vehicle. id; 

PO.DB.EITRY  •current.opaque.task.f me ; 
int32  nun. executing. tasks ; 

PO.0B.OmtY  *execut ing. tasks  □ ; 

‘entry*  Specifies  the  task  frame 
‘vehicle. id’ 

Specifies  the  vehicle  execution  context 

‘current.opaque.task.frasM’ 

Specifies  the  exectuing  opaque  task  frame  in  current  context 

‘nua.exectuing.tasks’ 

Specifies  the  number  of  executing  tasks  in  current  context 
‘exectuing_tasks’ 

Specifies  the  list  of  exectuing  tasks  in  current  context 


taskfr.check.enabling  returns  a  TRUE  or  FALSE  value  indicating  whether  the  enabling  tasks 
of  the  passed  task  frame  indicate  that  it  should  be  pushed. 


3.8  taskfr_get.jtasks 


int32  task* r_get.tasks (entry ,  tasks) 

PO.DB.EITRY  * entry; 

PO.DB.EITRY  *tasks  □ ; 

‘entry’  Specifies  the  task  frame 

‘tasks’  Returns  a  fist  of  tasks  in  the  task  frame 

taskfr.get.tasks  returns  a  list  of  tasks  in  the  passed  frame.  The  return  value  indicates  how 
many  tasks  were  returned. 


3.9  taskfr^subsequentjtask 


PO.DB.EITRY  *t askfr. subsequent .task (entry,  nodel) 
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PO.DB_QmiY  *  entry; 
uint32  Bodel; 

’entry’  Specifies  the  task  frame 

‘nodal’  Specifies  the  model  number  of  the  desired  task 

taskfr.subsequent.task  finds  the  task  with  the  specified  model  in  one  of  the  frames  subse¬ 
quent  to  the  passed  frame. 


3.10  taskfr-p  rim  ary -task 

PO.DB.EITRY  *taskfr.priaary.task(antry) 

PO.DB.EITRY  * entry; 

‘entry’  Specifies  the  task  frame 

taakfr.prinary.task  finds  the  primary  task  of  a  frame  (if  no  primary  task  can  be  found, 
returns  BULL). 


3.11  taskfr^taskjsearch 

P0.DB.EHRY  *taakf r.task.aearchCentry ,  nodal) 

PO.DB.EITRY  * entry ; 
uint32  nodal; 

‘entry’  Specifies  the  task  frame 

‘nodal’  Specifies  the  model  number  of  the  desired  task 

taskf r.task.search  finds  the  task  with  the  specified  model  in  the  passed  frame.  This  is  much 
more  efficient  than  finding  the  task  with  po.query.for.current.objects. 


3.12  taskfr.get -background-task 

PO.DB.EITRY  ♦taakf r_get.background.taak (db ,  unit. entry,  task.nodel) 
PO. DATABASE  *db; 
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PO.DB.EITRY  *unit_ entry; 
uint32  teak  .nodal ; 

‘db’  Specifies  the  PO  database 

‘unit.antry’ 

Specifies  the  unit  which  is  to  execute  the  task 
‘task.aodel’ 

Specifies  the  SAF  model  number  of  the  task 

taskfr.get_background.task  searches  the  background  frame  of  the  passed  unit  for  a  task  with 
the  specified  model. 


3.13  taskfr^et.background.task 


PO.DB.EITRY  *taskfr.set.background.task(db,  unit. entry,  task.aodel, 

paraa.size,  initial.paraas, 
state.size,  initial.state) 

PO.DATABASE  *db; 

PO.DB.EITRY  *unit_entry; 
uint32  task_aodal; 

uint32  par am. s ize ; 

ADDRESS  initial.paraas; 

uint32  state.size; 

ADDRESS  initial.state; 


‘db’  Specifies  the  PO  database 

‘unit. entry’ 

Specifies  the  unit  which  is  to  execute  the  task 
‘taskjaodeT 

Specifies  the  SAF  model  number  of  the  task 
‘paran.size’ 

Specifies  the  size  of  the  task  parameters 
‘initial.paraas' 

Specifies  initial  values  for  the  task  parameters  (or  NULL) 
‘state.size’ 

Specifies  the  size  of  the  task  state 
‘initial.state’ 

Specifies  initial  values  for  the  task  state  (or  NULL) 
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taskf r_set.background.task  ensures  that  a  task  of  the  specified  nodal  appears  in  the  specified 
unit’s  background  frame.  This  can  be  used  at  initialization  to  add  default  behavior  (such  as  task 
arbitration)  to  individual-level  units.  If  a  new  task  must  be  created,  it’s  parameters  and  state  are 
initialized  with  the  passed  values  (HULL  pointers  indicate  that  the  corresponding  data  should  be 
zeroed).  The  return  value  is  the  existing,  or  created,  task. 

Note  that  if  a  task  of  the  corresponding  model  is  found  (such  as  would  happen  after  a  vehicle 
migration),  the  task  is  not  changed. 


S.14  taskfr-update -background -task 

▼old  t  askf  r .updat e .background _  t  ask ( db ,  unit.entry,  task .nodal, 

nev.paraaeters ) 

PO.DATABASE  *db; 

PO.DB.EITRY  *unit .entry ; 
uint32  t ask_aodel ; 

ADDRESS  nev.paranetars ; 

’db’  Specifies  the  PO  database 

‘unit.entry’ 

Specifies  the  unit  executing  the  background  task 
‘taak.aodal’ 

Specifies  the  SAF  model  of  the  background  task 

‘new.paraaetera’ 

Specifies  the  new  parameters  desired 

taskfr.update.background.task  attempts  to  find  a  task  of  the  specified  nodal  in  the  specified 
unit’s  background  frame,  and  change  its  parameters  to  the  new  values. 


3.15  taskfr.get  Jabel 


char  * t askf r.get _ label (db,  entry) 
PO.DATABASE  *db; 

P0.DB.EMTRT  * entry; 


‘db’ 


Specifies  the  PO  database 
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‘entry’  Specifies  the  task  frame 

taakfr.get .label  finds  a  label  associated  with  a  task  frame.  It  attempts  to  find  the  label 
associated  with  the  first  object  referenced  by  the  primary  task  of  the  frame.  If  none  can  be  found, 
the  empty  string  " "  is  returned. 


S.16  t&skfr-jdelete-nll 


void  taakfr.delete.alKdb,  entry) 
PO.DATABASE  *db; 

PO.DB.ERTRY  * entry ; 


‘db’  Specifies  the  PO  database 

‘entry’  Specifies  the  task  frame 


taakfr.delete.all  deletes  all  the  tasks,  their  states  and  the  taskframe  itself. 
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4  Events 

The  following  sections  describe  each  event  provided  by  libtaskframe. 


4.1  taskfr.assignment-callback 

CALLBACK.EVEIT.PTR  taakfr.assignaent.callback; 

The  taskfr.assiguaant.callback  event  fires  in  response  to  the  unit  field  of  a  task  frame  being 
modified.  Note  that  this  callback  fires  outside  the  the  PO  object. changed  thread,  so  changes  to 
the  PO  database  in  handlers  are  perfectly  safe. 


The  handler  should  be  prototyped  as  follows: 


void  handler(db,  taakfraae) 
PO .DATABASE  *db; 
PO.DB.EMTRY  *taskf rane ; 
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1  O  verview 


The  tack  manager  is  responsible  for  running  all  the  tasks  in  the  current  frames  for  a  SAF  vehicle. 

The  algorithm  used  is  as  follows: 

1.  Get  a  list  of  roles  which  this  vehicle  is  playing  (such  as  company  commander,  platoon  leader, 
etc.).  One  of  these  roles  is  always  that  of  the  vehicle  itself. 

2.  For  each  of  those  roles,  determine  if  any  of  the  current  task  frames  have  been  unassigned. 
Remove  those  task  frames  from  the  stack. 

3.  For  each  of  those  roles,  determine  if  the  enabling  tasks  of  any  subsequent  frames  indicate  that 
those  frames  should  be  executed.  If  so,  start  one  new  frame.  The  frames  immediately  after 
the  topmast  frame  on  the  task  frame  stack,  and  those  immediately  after  the  topmost  opaque 
frame  on  the  stack  are  tested.  If  more  than  one  frame  is  enabled  simultaneously,  the  user  is 
notified,  and  one  is  chosen  arbitrarily  with  opaque  frames  chosen  over  transparent  frames. 

4.  For  each  role,  traverse  the  current  frames  (including  the  background  frame  and  all  frames  on 
the  task  frame  stack  down  to  the  first  opaque  frame)  and  collect  a  list  of  tasks  to  execute.  If 
a  task  of  a  certain  class  is  encountered  more  than  once,  only  the  first  occurence  will  be  kept. 
Currently  no  classification  is  done,  and  only  exact  SAF  model  redundancy  will  be  detected. 

5.  Sort  the  execution  list  such  that  the  before  and  after  restraints  of  each  task  are  not  violated 
(see  section  ‘task-register’  in  LibTask  Programmer’s  Manual). 

6.  Compare  the  resulting  list  of  tasks,  and  determine  if  any  tasks  which  were  executed  last  tick 
are  not  in  the  new  list.  Of  those,  suspend  those  which  are  still  running. 

7.  Execute  the  tasks  in  order. 
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2  Usage 


The  software  library  ‘libtaskagr.a’  should  be  built  and  installed  in  the  directory 
7coanon/lib/’.  You  will  also  need  the  header  file  ‘libtaekagr.h’  which  should  be  installed  in  the 
directory  '/canMm/include/libinc/*.  If  these  files  are  not  installed,  you  need  to  do  a  ‘make*  in 
the  libtaskmgr  source  directory.  If  these  files  are  already  built,  you  can  skip  the  section  on  building 
libtaskmgr. 


2.1  Building  Libtaskmgr 

The  libtaskmgr  source  files  are  found  in  the  directory  7cn— on/libarc/libtaakagr’.  ‘RCS’ 
format  versions  of  the  files  can  be  found  in  ‘/nfs/cci— on.src/libsrc/libtaskagr*. 

If  the  directory  ‘coanon/libsrc/libtaakagr’  does  not  exist  on  your  machine,  you  should  use 
the  ‘genbuild’  command  to  update  the  common  directory  hierarchy. 

To  build  and  install  the  library,  do  the  following: 

•  cd  cn—on/llbsrc/libtaahagr 

•  co  RCS/e,v 

•  aaka  install 

This  should  compile  the  library  ‘libtaskagr.a’  and  install  it  and  the  header  file  ‘libtaskngr.h’ 
in  the  standard  directories.  If  any  errors  occur  during  compilation,  you  may  need  to  adjust  the 
source  code  or  ‘Makef  lie’  for  the  platform  on  which  you  are  compiling,  libtaskmgr  should  compile 
without  errors  on  the  following  platforms: 

•  Mips 

•  SGI  Indigo 

•  Sun  Sparc 


2.2  Linking  with  Libtaskmgr 

Libtaskmgr  can  be  linked  into  an  application  program  with  the  following  link  time  flags:  ‘Id 
[source  .o  files]  -L/co— on/lib  -ltaskagr  [other  libraries]*.  If  your  compiler  does  not 
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support  ‘-L’  syntax,  you  can  use  the  archive  explicitly:  ‘Id  [source  .o  files] 
/coasoa/lib/Ubtaskagr .  s’. 

Libtaskmgr  depends  on  libdass,  libparmgr,  libpo,  librdreonst,  libreader,  libtask,  libtaskframe, 
and  libvtab. 
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3  Functions 


The  following  sections  describe  each  function  provided  by  libtaskmgr,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


3.1  taskmgrJnit 

void  taakagr.initO 

taskngr.init  initializes  libtaskmgr.  Call  this  before  any  other  libtaskmgr  function. 


3.2  taskmgr -register -reentrant-task 

void  t aalosgr.regiet er.reentrant .t ask  ( saf  jaodel ) 
uiat32  saf jaodel; 

‘saf  jnodeT 

Specifies  the  SAF  model  number  of  the  task 

taskagr.register.reeatrant.task  informs  the  taskmgr  that  the  specified  task  was  written 
such  that  it  can  be  executed  multiple  times  within  the  same  vehicle.  This  is  a  requirement  for  per¬ 
sistent  unit-level  background  tasks,  since  they  may  be  executing  on  multiple  levels  of  the  hierarchy 
simultaneously. 

In  this  context,  reentrant  implies  that,  like  an  enabling  task,  the  task  has  no  per-instantiation  pri¬ 
vate  state  variable.  Private  variables  which  provide  general  system  context  (such  as  a  PO.DATABASE) 
are  acceptable,  but  local  copies  of  information  held  in  the  shared  TaskState  structure  are  not. 


3.3  taskxngr-class -in it 


void  taskngr.class.lnlt (parent. class,  acceptance. callback) 
CLASS.PTE  parent .class; 

TASHfiat.ACCEPTAICE.TEST  acceptance.callback; 
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‘parent.class’ 

Class  of  the  parent  (declared  with  class.declare. class) 
‘acceptance.callback’ 

Specifies  function  to  call  to  determine  if  a  unit  accepts  an  assigned  order 


taakngr.class.init  creates  a  handle  for  attaching  taskmgr  class  information  to  vehicles.  The 
parent. class  will  likely  be  safobj .class. 


The  acceptance.callback  should  be  declared  as  follows: 


int32  acceptance.test (vehicle. id,  taskfrane) 
int32  vehicle. id; 

PO.DB.EVTRY  etaskfrssM; 


A  return  value  of  TRUE  indicates  that  the  unit  should  perform  the  assigned  taskframe;  FALSE 
indicates  that  the  unit  should  ignore  the  assigned  taskframe.  This  allows  an  application  to  model 
radio  message  loss,  insubordination,  etc.  Note  that  this  is  called  in  the  thread  of  a  LibPO  object 
changed  callback  (where  the  object  which  changed  is  the  passed  task  frame).  Thus  to  later  accept 
a  frame  which  was  originally  rejected,  an  application  should  modify  the  taskframe  to  trigger  a  new 
involution  of  this  callback. 

A  HULL  acceptance.callback  indicates  that  all  orders  should  be  accepted. 


3.4  taakmgr-create 


void  taskngr.create (vehicle. id,  p arena,  db) 
int32  vehicle. id; 

TASHfGK.PAEAllETEIC.DATA  *parans; 

PO.DATABASE  *db; 

id' 

Specifies  the  vehicle  ID 
Specifies  initial  parameter  velum 

Specifies  the  persistent  object  database  in  which  tasks  and  task  frames  can  be  found 

taskngr.create  creates  the  taskmgr  class  information  for  a  vehicle  and  attaches  it  to  the 
vehicle's  block  of  libdass  user  data. 


‘vehicle. 

‘parana’ 

‘db’ 
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3.5  taskmgr -destroy 

▼old  taskngr.destroy (vehicle. id) 
int32  vehicle. id; 


‘vehicle,  id’ 

Specifies  the  vehicle  ID 


tasksgr.destroy  frees  the  taskmgr  dess  information  for  a  vehide.  This  should  be  called  before 
freeing  the  dass  user  data  with  class_free.ua er.data. 


3.6  taskmgr-tick 

void  taakagr. tick (vehicle. id) 
int32  vehicle. id; 

‘vehicle. id’ 

Specifies  the  vehide  ID 

taskngr.tick  executes  the  algorithm  described  in  the  overview  of  this  document  (see  Chapter  1 
[Overview],  page  1). 


3.7  taskiagr-task^done 


P0.0B.EITRT  *taskagr.task.done(vehicle_id,  nodal) 
int32  vehicle. id; 
int32  nodal; 


‘vehicle. id’ 

Spedfies  the  vehide  ID 

*nodel’  Model  ID  of  a  task  to  query  for. 

taskngr.task.deae  checks  list  of  currently  executed  tasks  and  returns  a  pointer  to  the  task  if 
the  model  has  already  been  executed  during  this  iteration  of  the  taskmanager. 
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3.8  taakmgr_get-iask 


PO.DB.EITRY  •taskagr.get .task (vehicle. id,  aodel) 
lnt32  vehicle. id; 
iat32  aodel; 


‘vehicle. id' 

Specifies  the  vehicle  ID 

‘aodel’  Model  ID  of  a  task  to  query  for. 

teehagr.get.teak  searches  the  list  of  tasks  currently  being  executed  by  this  vehicle  for  one 
matching  the  passed  model,  and  returns  it.  If  non-NULL,  the  returned  object  is  guaranteed  to  be 
of  objectClassTask. 
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1  Overview 


LibTaskPri  provides  a  task  management  service  to  support  mutual  arbitration  (see  section  ‘Ar¬ 
bitration’  in  ModSAF  Programmer’s  Guide).  Tasks  register  the  criteria  under  which  they  need  to 
control  a  critical  resource  (such  as  output  to  an  acutator  like  the  hull),  and  each  tick  these  criteria 
are  resolved  against  a  set  of  priorities  to  determine  which  task  gets  that  resource  for  that  tick. 

Criteria  for  deciding  when  the  resource  should  be  controlled  can  be  very  simple  (e.g.,  whenever 
the  task  is  running)  or  quite  complicated,  involving  tests  of  task  state,  the  state  of  other  tasks, 
etc.  One  way  to  deal  with  this  sort  of  complexity  is  to  use  callback  functions  to  make  these 
determinations.  However,  in  many  cases  this  is  more  than  is  really  needed,  and  would  certainly 
lead  to  a  lot  of  very  similar  code  repeated  throughout  the  system. 

Instead,  liblhskPri  defines  a  simple  meta-language  in  which  the  logical  combinations  which 
make  up  the  criteria  are  put  together  in  a  data  structure  which  is  parsed  at  run  time.  C  macros 
are  provided  to  give  th?  definition  of  this  structure  the  fed  of  a  programming  language. 

The  AAFSM  code  generator  (see  section  ‘AAFSM  Code  Generator’  in  LibTask  Programmer’s 
Manual)  is  aware  of  libTaakPri,  and  provides  convenient  notation  for  interfacing  to  this  library. 
Thus,  many  tasks  which  use  libTaskPri  never  explicitly  call  libTaakPri  functions  (they  are  called 
by  generate  code,  instead). 

Each  SAF  object  has  an  instance  of  the  TankPriority  subclass,  which  has  parameters  in  the 
following  format: 

(SM_TaakPr iorit y  (tanks 

("<group  naae>"  <SAF  Hodel>  <SAF  Model>  <SAF  Model>...) 
("<group  niM>"  <SAF  Model>  <SAF  Model>  <SAF  Modsl> .  . ) 

•  •  • 

) 

) 

The  group  naae  is  a  character  string  identifying  the  resource  which  needs  arbitration.  This 
name  is  passed  to  libTaskPri  in  the  registration  and  predicate  functions,  to  identify  the  resource  at 
run  time. 


The  SAF  Models  listed  express  the  priority  of  tasks  which  may  control  the  resource.  The  order 
of  these  numbers  implies  a  prioritization,  with  earlier  tasks  taking  higher  priority. 
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When  the  program  is  running,  the  tasks  selection  process  can  be  viewed  in  real  time  by  enabling 
taskpri  debugging. 


Chapter  2:  Logic  Meta-Language 
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2  Logic  Meta-Language 


The  logical  expression  which  is  used  to  determine  whether  a  task  wants  to  control  a  resource 
is  specified  using  a  data  structure,  organized  as  a  post-fix  (RPN)  list  of  instructions.  However,  to 
improve  readability  and  to  reduce  errors,  as  set  of  C  macros  can  be  used  to  construct  this  data 
structure  more  readably. 

The  macros  are  as  follows: 

TASKPRI.EVD 

Specifies  the  end  of  a  list  of  instructions.  This  should  always  be  the  last  thing  specified. 

TASKPRI.AID(expr ,  expr) 

TRUE  if  both  expressions  evaluate  to  TRUE. 

TASKPRI .AIDS (expr,  expr,  expr) 

TASKPRI_AMD4(expr,  expr,  expr,  expr) 

TASKPRI.  AIDS  (expr,  expr,  expr,  expr,  expr) 

TASKPRI.  AIDS  (expr,  expr,  expr,  expr,  expr,  expr) 

TRUE  if  all  their  expressions  evaluate  to  TRUE. 

TASKPRI _0R (expr,  expr) 

TRUE  if  either  expression  evaluates  to  TRUE. 

TASKPRI.0R3(expr,  expr,  expr) 

TASKPRI.0R4(expr,  expr,  expr,  expr) 

TASKPRI_0R5(expr ,  expr,  expr,  expr,  expr) 

TASKPRI. 0R6 (expr,  expr,  expr,  expr,  expr,  expr) 

TRUE  if  any  of  their  expressions  evaluate  to  TRUE. 

TASKPRI.IOT(expr) 

TRUE  if  the  expression  is  FALSE. 

TASKPRI.RUHIIG 

TRUE  when  the  task  is  in  any  "running"  state  (all  but  the  FSM-generated  not  .started, 
endied,  suspended). 

TASKPRI. II.STATE(state) 

TRUE  when  the  task  is  in  the  specified  state. 

TASKPRI  .SELECTED  (task  nodel,  group) 

TRUE  when  the  other  specified  task  has  been  selected  to  provide  output  for  the  specified 
group. 

TASKPRI _ FUMCTI 01  (function ,  argument) 

The  return  value  of  the  invocation 
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function(vehicle_id,  argument ,  taek. entry,  state.entry) 
int32  vehicle. id; 

iat32  arguaent ; 

PO.DB.EKTRY  *ta*k. entry; 

PO.DB.EKTRY  *stat e.antry ; 


See  the  example  (see  Section  2.1  [Examples],  page  4)  for  sample  usage. 


2.1  Examples 


Task  provides  output  if  in  any  running  state  except  idle,  unless  in  the  needy  state,  in  which  case 
only  if  task  SM.Helper  is  controlling  the  "helper"  group,  and  the  function  ready  with  argument 
3  returns  TRUE: 


(running  ft ft  ! (state  ■"  idle)  ftft 
( ! (state  ■*  needy)  1 1 

( (SM.Helper  is  selected  for  "helper")  ftft  ready(3)))) 


Is  expressed  as: 


TASKPRI .LOGIC  stack  □  •  < 

TASKPRI_A1D3(TASKPRI_RUV1IIG , 

TASKPRI _10T (TiSKPRI _ II.STATE (idle) ) , 

(TASKPRI _OR(TASKPRI _K0T (TASKPRI .II.STATE (needy) ) , 
TASKPRI .AID (TASKPRI .SELECTED (SM.Helper , 

"helper") , 

TASKPRI. FUICTIO* (ready.  3) 

) 

) 

) 

) 

TASKPRI _EID  >; 


t askpri.register.f or. group (SM.nyt  ask , 

TASKPRI .OFFSET (MYTASK.STATE) , 
reader _get.syabol("ay-actuator") , 
stack) ; 
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3  Functions 

The  following  sections  describe  each  function  provided  by  libtaskpri,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 

3.1  taskprUnit 

void  taskpri.initO 

taskpri.init  initializes  libtaskpri.  Call  this  before  any  other  libtaskpri  function. 


3.2  taskpri_register.ibr.group 

void  taskpri.ragieter_for_group(nodel,  state.of f set ,  group.synbol ,  criteria) 
uint32  nodal; 

uint32  state.of f set ; 

char  egroup.sjribol; 

TASKPRI .LOGIC  * criteria; 

'nodal’  Specifies  the  model  number  of  the  task 
'stata.offsat’ 

Specifies  the  address  of  the  state  variable  state  within  the  task  state  data  structure 
‘group.synbol’ 

Specifies  the  name  of  the  group  which  is  to  be  controlled,  as  a  libreader  symbol  (see 
section  ‘reader -getjymbol’  in  LibReader  Programmer’s  Manual) 

‘criteria’ 

Specifies  the  execution  criteria  (see  Chapter  2  [Logic  Meta-Language],  page  3) 

taskpri.ragistar.for.group  registers  the  method  by  which  a  task  will  indicate  whether  it 
wants  to  run  a  group.  The  statejoffset  can  be  conveniently  passed  as 

TASKPRI..  OFFSET  (  <TASXIAME>  .STATE) 

The  criteria  are  presented  as  a  logical  collection  of  primitives  in  post-fix  order.  The  logic  is 
assumed  to  be  stored  in  non-volatile  (global,  static,  or  dynamically  allocated)  memory. 
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S.S  tmskpri-class-init 


▼old  taakpri.claaa.init (parent. class) 

CLASS.PTR  parent. daaa; 

‘parent.class’ 

Class  of  the  parent  (declared  with  claaa.daclare.daaa) 

taskpri. dass.init  creates  a  handle  for  attaching  taskpri  class  information  to  vehicles.  The 
parent.claaa  will  likely  be  aafobj.claaa. 


S.4  taskpri-create 


void  taskpri.create(vehicle.id,  par  ana,  db) 
int32  vehicle. id; 

TASXPlU.PARANETRIC.DATi  vparaas; 
PO.DATABASE  *db; 


‘vehide.id’ 

Specifies  the  vehicle  ID 

‘par aa^’  Specifies  initial  parameter  values 

‘db’  Specifies  the  PO  database 

taakpri.create  creates  the  taskpri  class  information  for  a  vehicle  and  attaches  it  vehicle’s 
block  of  libdass  user  data. 


S.5  taakpri-deatroy 

void  taakpri.destroy(vehide.id) 
int32  vehide.id; 

‘vehide.id’ 

Specifies  the  vehicle  ID 

taakpri.deatroy  frees  the  taskpri  class  information  for  a  vehicle.  This  should  be  called  before 
freeing  the  class  user  data  with  dasa.free_nser.data. 
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3.6  taakpri  jelect 


void  taakpri.select  (vahicle.id ,  n. execs,  exec.list) 
int32  vehicle. id; 

int32  n.execs ; 

P0.0B.EITRY  *«z«c.listQ ; 

'vahicle.id' 

Specifies  the  vehicle  ID 

‘n.execs’  Specifies  the  number  of  tasks  which  will  be  executed 
‘exec. list’ 

Specifies  the  tasks  which  will  be  executed 


taskpri.select  selects  which  of  the  tasks  which  are  going  to  be  run  will  be  allowed  to  provide 
output  this  tick.  This  is  run  as  part  of  the  task  management  algorithm. 


3.7  taskpriuenabled 

int32  taskprl.enabled (vehicle. id.  group. symbol ,  task) 
int32  vehicle. id; 

char  *group_syabol ; 

PO.DB.EITRY  *task; 

‘vehicle. id’ 

Specifies  the  vehicle  ID 
‘group,  syabol’ 

Specifies  the  name  of  the  group  which  is  to  be  controlled,  as  a  libreader  symbol  (see 
section  ‘reader.getjymbol’  in  LibReader  Programmer’s  Manual) 

‘task’  Specifies  the  task  which  wants  to  provide  output 

taskpri.unabled  returns  whether  the  passed  task  has  been  selected  to  provide  output  this  tick 
for  the  specified  group. 
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1  O  vervie w 


Libtdbtool  is  a  tool  for  calculating  intervisibility  between  points,  in  a  terrain  area,  in  a  vehicle 
area,  and  between  vehicles.  It  uses  libctdb  to  find  the  elevation  and  determine  the  visibility  at  each 
point.  The  tool  also  provides  a  cross  section  of  the  terrain.  There  are  four  types  of  intervisibility 
that  can  be  performed:  terrain  point-to-point,  terrain  area,  vehicle  point-to-point  and  vehicle  area. 
For  terrain  point-to-point,  the  cross  section  of  that  line  is  also  calculated,  as  well  as  the  distance 
between  the  starting  and  ending  points,  and  the  coordinates  of  the  start  and  end  points.  The 
line  that  is  drawn  on  the  screen  for  terrain  point-to-point  shows  green  for  fully  visibile,  green- to- 
black  dithered  for  partially  visible  and  black  for  blocked.  The  line  also  contains  tick  marks  at  the 
same  interval  as  the  current  grid  on  the  screen.  Libtdbtool  uses  two  tactmap  objects  to  display  in 
intervisiblity  on  the  screen.  See  libtactmap  for  more  information. 
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2  Functions 


The  following  sections  describe  each  function  provided  by  libtdbtool,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  tdbtool-init 

void  tdbtool.initO 

tdbtool.init  initializes  libtdbtool.  Call  this  function  before  calling  any  other  libtdbtool  func¬ 
tions. 


2.2  tdbtool_create^editor 


int32  tdbtool. create. editor (data. path,  reader.f lags , 

gui,  tactaap,  tcc,  ctdb,  aap.erase.gc, 
sensitive,  ref rash. event ,  db,  pvd, 
ref resh. control. callback ,  refresh.control.arg) 
* data. path; 
reader.f lags ; 
gui; 

tactaap; 
tcc; 

*ctdb; 

aap.erase.gc ; 

SMSTVE.WIMDOW.PTR  sensitive; 

CALLBACK.EVE1IT.PTR  ref  resh.  event  ; 

PO.DATABASE  *db; 

PVD.GUI.PTR  pvd; 

void  (*refresh_control_callback) () ; 

ADDRESS  ref resh. control.arg; 


char 

int32 

SGUI.PTR 

TACTMAP.PTR 

COORD.TCC.PTR 

CTDB 

GC 


‘data.path’ 

Specifies  the  directory  where  data  files  are  expected 
‘reader.flags’ 

Specifies  flags  to  be  passed  to  reader.read  when  reading  data  files 
‘gui’  Specifies  the  SAF  GUI 
‘tactaap’  Specifies  the  tactical  map 
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‘tec’  Specifies  the  map  coordinate  system 

‘ctdb’  Specifies  the  terrain  database 

‘aap.srass.gc’ 

Specifies  the  GC  which  can  erase  things  from  the  tactical  map 

‘sensitive’ 

Specifies  the  sensitive  window  for  the  tactical  map 
‘refresh,  event’ 

Specifies  the  event  which  fires  when  the  map  is  refreshed 
‘db’  Specifies  the  persistent  object  database 

‘pvd’  Specifies  the  PVD 

‘refresh. control. callback’ 

Specifies  the  rontine  to  call  when  the  terrain  tools  is  started  to  turn  off  refreshing  the 

non-terrain  of  the  tactmap 
‘rsfrssh.control.arg’ 

Specifies  the  refresh  terrain  event  to  be  turned  on  and  off. 

tdbtool.create.editor  creates  the  tdbtool  editor.  The  data  file  (‘tdbtool.rdr’)  is  read  either 
from  ‘ .  ’  or  the  specified  data  path,  depending  upon  the  rsadsr.flags.  The  rsadsr.f lags  are 
as  in  rsadsr.rsad.  The  return  value  is  zero  if  the  read  succeeds,  or  one  of  the  libreader  return 
values:  READER.READ.ERROR,  READER.FILE.HOT.FOUID.  When  the  tdbtool  editor  is  invoked,  the 
non  terrain  refresh  in  the  tactmap  is  turned  off.  It  is  turned  back  on  when  the  tod  is  exited. 
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1  Overview 


Libtime  supports  two  millisecond  resolution  clocks:  a  real  time  clock  which  is  driven  by  the 
system,  and  a  simulation  clock  which  moves  at  a  constant  positive  factor  *  real  time.  A  simulation 
clock  in  DIS  time  units  is  also  provided. 

The  library  also  provides  functions  for  use  with  the  Persistent  Object  protocol  TimeDateGroup 
structure,  as  well  as  conversion  macros  to  convert  between  DIS  and  millisecond  time  units. 
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2  Examp  les 

To  get  the  value  of  the  real  time  clock: 
uint32  t; 

t  ■  time.realtime.clockO ; 

To  get  a  recent  value  of  the  real  time  clock,  without  the  expense  of  reading  the  system  clock: 
uint32  t; 

t  ■  tlme.last.realtinw. clock; 

Given  a  known  unix  time  (seconds  since  1970),  generate  the  appropriate  TimeDateGroup: 


•include  <p_po.h> 

TimeDateGroup  tdg; 

t iae_tdg_f rom_seconds (unix_aeconda ,  ttdg) ; 
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3  Fun  ctio  n  s 


The  following  sections  describe  each  function  provided  by  libtime,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


3.1  timejnit 

void  tine.initCmax.forvard.step) 
uint32  max.f orvard.step ; 

‘naz.forvard.step’ 

Specifies  maximum  reasonable  time  increment  between  calls. 

tine.init  initializes  libtime.  Resets  clocks.  The  nax_forvard_step,  if  non-zero,  specifies  the 
most  real  time  which  may  pass  between  successive  calls  to  tim#_advancs_sinulation_clock  or 
tims.rsaltins.clock.  For  example,  passing  a  fairly  large  value  (such  as  1000  ms)  will  automati¬ 
cally  cause  time  to  stop  advancing  when  single  stepping  with  a  debugger. 


3.2  time jad  vance.simulation_clock 
uint32  t iiM.advancs.simul ation. clock () 

tin*.advasc«_sinulation_clock  returns  the  time  of  the  simulation  clock  in  milliseconds. 


3.3  timejrealtime jclock 

uint32  tina.raaltine.clockO 

tine.rvaltiaw.clock  returns  the  time  of  the  real  time  clock  in  milliseconds. 


6 


LibTime  Programmer’s  Guide 


3.4  time Jast .simulation-clock 

uint32  tlM.last.aiBulation.dock 

tiM.last.siaulation.dock  retains  the  last  value  returned  by 
tiM.advance.simulation.dock. 


3.5  time  Jast  .aim  ulation.jd  is. clock 
uint32  tiM.last.siaulation.dis. clock 

tiM.last.siBulation.dis. dock  retains  the  last  value  returned  by 
tiM.advance.siBulation.dock,  expressed  in  DIS  time  units.  In  DIS,  the  mo6t  significant  31 
bits  of  a  32-bit  time  field  contains  the  time  in  units  of  the  following  duration:  1  hour  =  2*31-1  time 
units.  This  time  implements  DIS  relative  timestamping,  and  the  least  significant  bit  is  always  0. 


3.6  time  Jast  .realtime  .clock 
uint32  tiM.last.realtiBe.dock 

tine.last.realtiM.dock  retains  the  last  value  returned  by  tine.realtiM.dock. 


3.7  time .set .simulation .rate 


void  tiM.set.8iaulation.rato(positive.Bultiplier,  limit) 
float64  positive.multiplier; 
uint32  limit; 


‘positive_multiplier’ 

Specifies  the  rate  of  simulation  relative  to  real  time. 

‘limit’  Specifies  a  simulated  time  to  reach  before  it  is  time  to  go  back  to  the  rate  1.0  x  real 
time. 
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tiM_set.aimlation.rate  sets  the  relationship  between  the  simulation  clock  and  real  time. 
If  a  non-zero  value  is  given  as  the  limit,  the  simulation  rate  will  switch  back  to  1.0  when  that 
simulated  time  is  reached. 


3.8  time jiimulation.to .realtime 

uint32  time_simulation_to.realtime(simulation_clock) 
uint32  simulation. clock; 

‘simulation. clock’ 

Specifies  a  simulation  clock  time. 

tim.simulation_to.realtiM  determines  the  real  time  which  corresponds  to  the  passed 
simulation_dock  time,  given  the  current  simulation  rate  (of  course,  if  the  simulation  rate  changes 
before  the  passed  simulation_clock  time  is  reached,  this  answer  will  be  incorrect). 


3.9  tim e_p arse _d ate 

uint32  time.parse.date(date.string) 
char  *date.string; 

‘date.string’ 

Specifies  "YYMMDD"  string  to  parse. 

tiM.parse.date  given  a  string  of  the  form  "YYMMDD",  returns  an  integer  with  the  value 
YYMMDD.  Returns  0  if  the  date  is  not  of  the  correct  format. 


3.10  time  .parse-time 

uint32  tim.parse.timeCtime.string) 
char  *tiM_string; 

‘time  .string’ 

Specifies  "HHMM"  string  to  parse. 
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Given  a  string  of  the  form  "HHMM",  time.parse.tiM  returns  an  integer  with  the  value 
HHMM.  It  returns  -1  if  the  time  is  not  of  the  correct  format. 


3.11  time_tdg_from  .seconds 


void  tiM.  tdg.  froa.  seconds (seconds,  tdg) 
uint32  seconds ; 

TiMDateGroup  *tdg; 


‘seconds*  Specifies  a  unix  time. 

‘tdg’  Returns  a  protocol  time-date-group  structure. 


Given  a  “unix"  time  (seconds  since  1970),  t iae. tdg_f roa. seconds  fills  in  the  passed  Time- 
DateGroup  structure. 


3.12  time.tdg_from^date_time 


void  tiae.tdg.froa_date.tiM (date,  tiae,  tdg) 
uint32  date ; 

uint32  tiae; 

TiMDateGroup  *tdg; 


‘date’  Specifies  a  date  in  YYMMDD  format. 

‘tiM’  Specifies  a  time  in  HHMM  format. 

‘tdg’  Returns  a  protocol  time-date-group  structure. 


Given  a  date  in  the  form  YYMMDD  and  a  time  in  the  form  HHMM,  tine_tdg_froa.date.tiM 
fills  in  the  passed  TimeDateGroup  structure. 


3.13  time.tdg.from -Unix 

void  tiM.tdg_froa_unix(tdg) 

TiMDateGroup  *tdg; 

‘tdg’  Returns  a  protocol  time-date-group  structure  filled  in  with  current  unix  time. 
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ti^«tdg.fro«_unix  fills  in  the  passed  TimeDateGroup  structure,  based  upon  the  result  of  a 
call  to  unix  tine. 
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4  M  acros 

The  following  sections  describe  each  macro  provided  by  libtime,  including  the  format  and  mean¬ 
ing  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 

4.1  T IM  E  _M  S  _T  O  _D  IS  JF  A  C  T  O  R 

TIKE_MS_TO_DIS_FACTOR 

TINE.NS.TO.OIS.FACTOR  is  defined  as  the  number  of  DIS  time  units  in  a  millisecond.  It  is  equal 
to  (2*31  -  1)  /  60  *  60  *  1000. 

4.2  T IM E _M S _T O JD IS 

TIME_MS_T0_DIS(t) 

‘t’  Specifies  a  time  in  milliseconds 

TIME_MS_T0_DIS  returns  the  time  t,  passed  in  as  milliseconds,  as  DIS  time  units. 

4.3  TIME JDIS_TO_MS 

TIME_DIS_T0_MS(t) 

‘t’  Specifies  a  time  in  DIS  time  units 

TIME_DIS_T0_MS  returns  the  time  t.  passed  in  as  DIS  time  units,  as  milliseconds. 
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1  Overview 


Libtracked  implements  an  instance  of  the  hull  class  of  components.  It  provides  a  low-fidelity 
model  of  tracked  vehicle  dynamics.  Capabilities  are  modeled  only  to  the  second  order  (maximum 
velocity,  maximum  acceleration),  and  they  depend  upon  the  soil  type.  Unlike  previous  models, 
the  parameters  for  each  soil  type  are  specified  in  a  data  file,  so  the  software  does  not  need  to  be 
modified  to  accommodate  new  types  of  terrain. 

The  parameters  of  a  tracked  vehicle  are  specified  in  its  configuration  file  as  follows: 


(tracked  (soil'  (cinteger  soil  type>  (max.speeds  <float  forward  KPH> 

< float  reverse  KPH>) 
(max.accel  <float  mp«2>) 
(max.decel  <float  mps2>) 

(max. turn  <float  dps>) 

(max_ climb  <float  degrees >) 
(dust.speeda  <float  smallKPH> 
<float  mediumKPH> 
<float  largeKPH») 

(< integer  soil  type>  (max. speeds  <float  KPH> 

<float  reverse  KPH>) 
(max.accel  <float  mps2>) 
(max.decel  <float  mps2>) 

(max. turn  <float  dps>) 

(max. climb  <float  degrees >) 
(dust.speeda  <float  smallKPH> 
<float  mediumKPH> 


) 


<float  largeKPH>)) 

•  •  •  ) 

(fuel.usage  (<float  apeedl>  <float  speed2>  ...) 

(<float  ratel>  <float  rate2>  ...)) 


The  parameters  specified  for  soil  type  0  (or  the  first  soil  type,  if  no  0  type  is  provided)  are  used 
as  a  default  when  on  a  soil  type  not  in  the  list. 

To  indicate  that  the  vehicle  should  not  kick  up  any  dust  on  a  kind  of  soil,  specify  a  speed  which 
is  higher  than  the  maximum  the  vehicle  can  travel  across  that  soil. 

The  fuel-usage  table  consists  of  a  list  of  speeds  in  kilometers  per  hour,  with  a  list  of  corresponding 
consumption  rates  in  liters  per  hour.  If  an  older  vehicle  parameter  file  is  used,  with  a  scalar 
fueLusage  figure,  it  will  ignore  it  and  use  the  internal  default  corresponding  to  8  kilometers  per 
liter.  The  minimum  table  size  is  one  speed/rate  pair. 
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Applications  interface  to  the  tracked  model  primarily  through  the  libhulls  interface.  The  most 
efficient  interface  for  controlling  vehicle  motion  is  HULLS.SET.DIRECTION.SPEED.  All  interfaces  use 
only  two  dimensions  of  the  provided  parameters.  Also,  when  a  direction  vector  is  given  it  is  not 
necessary  to  make  that  vector  a  unit  vector.  Libtracked  will  do  the  normalization  only  if  it  is 
necessary  (for  example,  if  the  vehicle  is  already  pointing  the  right  way,  no  normalization  is  needed). 

Libtracked  supports  only  one  instantiation  per  vehicle  (i.e.,  a  vehicle  may  not  have  more  than 
one  tracked  hull). 

The  libhulls  library  defines  a  common  set  of  functions  (and  the  semantics  of  those  functions) 
which  are  invoked  on  instances  of  the  hulls  class  (such  as  those  instantiated  by  libtracked  or  libfwa). 
It  is  possible  to  modify  the  tracked  model  by  changing  an  exisiting  hulls  interface  function  or  by 
adding  a  completely  new  function. 

To  modify  an  existing  libtracked  interface  function  would  require  the  following  actions: 

1.  If  the  change  occurs  only  in  the  function  body,  only  change  the  function  code  in  the  libtracked 
library.  If  the  change  occurs  to  the  function’s  argument  list,  change  the  function  code  in  both 
the  libtracked  library  and  the  hulls  interface  structure  definition  found  in  libhulls.h.  Also  to 
maintain  the  common  hulls  interface,  change  the  code  for  the  modified  function  in  any  other 
hull  specific  component  libraries  (such  as  libfwa  or  libmissile). 

2.  Recompile  ModSAF. 

To  add  an  additional  libtracked  function  to  the  current  model  would  require  the  following  actions: 

1.  Write  the  function  as  part  of  the  libtracked  library.  The  function  is  written  in  the  code  which 
manages  the  libtracked  class  information  attached  to  each  vehicle  (trk_class.c). 

2.  Add  the  function  and  its  declaration  to  any  of  the  other  hull  specific  component  libraries.  This 
maintains  the  common  hulls  interface. 

3.  In  the  libtracked  source  code  that  handles  libhull  initialization  processing,  include  a  func¬ 
tion,  number,  function  entry  identifying  the  new  function  for  the  cmpnt.define. instance 
function  and  every  other  hull  instance  library  (libfwa,  libmissile,  etc.). 

4.  In  libhulls.h,  add  an  entry  to  identify  the  new  macro  and  associate  it  with  a  function  code 
number.  This  new  addition  means  that  the  number  of  hulls  functions  must  be  incremented  by 
one.  The  hulls  interface  structure  definition  that  appears  in  libhulls.h  must  include  a  structure 
to  define  the  new  function’s  argument  list. 

5.  Recompile  ModSAF. 
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To  replace  this  tracked  model  with  a  completely  different  one  would  require  the  following  actions: 

1.  Decide  on  the  get  functions  and  set  functions  that  would  be  required  in  the  new  model.  Try  to 
map  these  needed  functions  to  the  existing  hulls  interface.  A  function  can  map  if  its  argument 
list  can  remain  the  same.  Functions  that  can  not  map  must  be  added  to  the  hulls  interface. 

2.  For  those  functions  that  can  map  to  the  existing  hulls  interface  but  whose  code  body  you  want 
to  change,  edit  the  code  for  the  function  in  the  libtracked  source  file  that  contains  the  code  to 
manage  the  libtracked  class  information  (trk-class.c). 

3.  For  those  functions  that  can’t  map  to  the  existing  hulls  interface,  add  an  additional  function 
to  the  hulls  interface.  The  addition  procedure  was  described  above. 

4.  Recompile  ModSAF. 
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2  Examp  les 

To  get  the  component  number  of  my  hull: 
extern  int32  my.hull; 

if  ((my.hull  *  cmpnt_locate( vehicle. id,  reader.get.symbolC'hull11)))  *■ 
CMPIT.HOT.FOUMD) 

printf  ("Vehicle  Xd  does  not  seem  to  have  a  hull\n" ,  vehide.id) ; 

To  then  give  a  command  to  that  hull: 
if  (my .hull  !■  CKPMT.HOT.FOUVD) 

HULLS_SET_DIRECTION_SPEED(vehicle_id,  hull,  dirvec,  speed,  0.0,  0.0); 
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3  Functions 


The  following  sections  describe  each  function  provided  by  libtracked,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


3.1  trackedJmit 

void  tracked.  initO 

tracked. init  initializes  libtracked.  Call  this  before  calling  any  other  libtracked  functions. 


3.2  tracked .jclass Jnit 

void  tracked_claaa_init(parent.class) 

CLASS.PTR  parent. class ; 

‘parent.class’ 

Class  of  the  parent  (declared  with  class.declare.dass). 

tracked.class.init  creates  a  handle  for  attaching  tracked  class  information  to  vehicles.  The 
parentjdass  is  one  created  with  class jdeclare .class. 


3.3  tracked_tick 


void  tracked.tickCvehicle.id,  ctdb) 
int32  vehicle. id; 

CTDB  *ctdb; 


‘vehicle. id’ 

Specifies  the  vehicle  ID 

‘ctdb’  Specifies  the  terrain  database  the  vehicle  is  operating  on. 


tracked.tick  ticks  the  tracked  hull  dynamics  model. 
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3.4  tracked_collision 

void  tracked. collisionC vehicle. id,  position,  coll.type, 

other. id,  other.mass,  other. velocity) 

int32  vehicle. id; 

float64  position [3] ; 
uint32  coll.type; 
int32  other. id; 

float64  other .mass; 
floated  other. velocity [3] ; 

‘vehicle.id' 

Specifies  the  vehicle  ID 

‘position’ 

Specifies  the  position  of  impact  in  world  coordinates 

‘coll.type’ 

Specifies  the  type  of  collision 

‘other. id’ 

Specifies  the  vehicle  ID  of  the  other  party  (or  0  if  terrain) 

‘other,  muss’ 

Specifies  the  mass  of  the  other  party 
‘other. velocity’ 

Specifies  the  velocity  of  the  other  party 

tracked.collision  tells  the  tracked  hull  dynamics  model  that  a  collision  occured.  The  colLtype 
should  be  one  of  the  libcollision  constants: 

COLL. TREES 

Indicates  crossing  a  treeline  or  canopy  edge. 

COLL.BUILOIMGS 

Indicates  crossing  a  building  or  other  structure.  If  the  other  structure  is  represented 
on  the  network,  the  vehicle  ID  of  that  structure  should  be  provided. 

COLL.GROUHD 

Should  not  be  checked  for  around  vehicles. 

COLL.PLATFORHS 

Indicates  intersecting  a  platform  (vehicle,  DI,  etc.). 

COLL.MISSILES 

Indicates  intersecting  a  (an  entity  on  the  network  with  a  munition  type. 
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3.5  tracked -dam  age 

void  tracked. daaage (vehicle. id,  d usage) 
int32  vehicle. id; 
int32  deaage; 

‘vehicle.id’ 

Specifies  the  vehicle  ID 

‘duuge’  Specifies  whether  the  tracked  dynamics  should  simulate  being  damaged 

tracked.daaage  tells  the  tracked  hull  dynamics  model  that  it  is  damaged  (or  not)  depending 
on  the  boolean  value  of  the  damage  flag. 
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1  O  verview 


Turrets  is  a  SAF  components  class.  The  purpose  of  a  components  class  is  to  define  a  common 
set  of  functions  which  are  invoked  on  instances  of  that  class,  and  the  semantics  of  those  functions. 
Other  than  defining  these  functional  semantics,  components  classes  don't  actually  *do*  anything. 


Access  to  turret  functions  is  achieved  through  macros  defined  by  libturrets.  These  macros  invoke 
‘cmpntjnvoke’  with  a  code  number  which  identifies  the  function  to  run.  Libcomponents  then  runs 
this  function  for  the  particular  turret  mode  via  a  jump  table. 

The  table  below  shows  how  the  turret  component  relationships  have  been  currently  implemented 
via  the  ModSAF  library  structure. 

specific  libraries  generic  library  architectural  library 
libgenturret  libturrets  libcomponents 

As  mentioned  above,  libturrets  requires  the  services  of  libcomponents,  an  architectural  library 
which  provides  a  level  of  abstraction  away  from  the  specific  turret  component  interfaces.  When  the 
ModSAF  application  gets  set  up  to  run,  the  libturrets  initialization  process  directs  libcomponents 
to  define  a  turrets  component  class.  This  information  enables  libcomponents  to  define  a  structure 
to  accommodate  all  of  the  turret  instantiations  a  simulated  object  is  allowed  to  have.  The  libturrets 
initialization  process  also  tells  libcomponents  the  number  of  its  defined  turret  interface  functions. 
This  enables  a  simulated  object’s  user  data  to  be  allocated  enough  space  to  hold  the  address  of 
each  of  the  interface  interface  functions  defined  in  libturrets. 


The  parametric  data  of  libcomponents  identifies  each  component  that  needs  to  be  modeled  when 
a  vehicle  is  simulated.  For  example,  a  component  entry  for  a  T72  tank  might  look  like  this:  (see 
the  file  named  USSR_T72M_params.rdr) 


(SM_ Components  (hull  SM_TrackedHull) 

(turret  SM_GenericTurret) 

(machine-gun  [SM.BallisticGun  I  0]) 
(main-gun  [SM_BallisticGun  I  1]) 
(visual  SM_ Visual)) 


A  T72M  simulated  vehicle  ( which  belongs  to  the  safobj  class)  will  have  component  sub-class  data 
that  tells  the  ModSAF  software  to  maintain  a  structure  that  includes  one  libgenturret  instantiation. 
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Since  an  application  will  interface  to  libgenturret  through  libturrets,  a  tank’s  turret  control 
commands  (which  are  performed  by  libgenturret)  are  issued  via  the  interface  defined  by  libturrets. 
Similarly,  an  application  can  obtain  information  about  the  state  of  its  turret  though  the  libturrets 
interface.  The  table  below  shows  the  relationship  between  the  specific  and  generic  library  for  the 
turrets  component. 

Instantiation*  of  Belong  to  generic  Have  a  command 

of  the  library:  component  class:  interface  defined  in: 

libgenturret  turrets  libturrets 

The  interface  to  libturrets  is  defined  in  its  public  header  file  (libturret.h).  Applications  interface 
to  the  generic  turret  model  primarily  through  the  macros  defined  in  libturrets.  These  macros 
map  to  functions  which  are  invoked  on  instances  of  the  turrets  sub-class  (such  as  the  libgenturret 
component  instantiated  for  a  tank). 

One  interface  for  controlling  a  turret  is  the  TURRETS_SET_ AZIMUTH  macro  which  maps  to  a 
function  that  sets  the  desired  azimuth  (in  vehicle  coordinates)  of  the  turret,  and  instructs  the 
turret  to  move  to  that  azimuth  in  an  optimal  way  for  target  tracking.  A  possible  definition  for  this 
macro  is  shown  below. 


•define  TURRETS_SET_AZIMUTH(_vid ,  _cnum,  _&zim) 

TURRETS. INTERFACE  .tif; 

_ t if .u.set.azimuth. azimuth  ■  _&zim; 

cmpnt_invoke(TURRETS_SET_ AZIMUTH.FCN ,  _vid,  .cnum,  (ADDRESS) A. tif) ; 


The  TURRETS.INTERFACE  structure  defined  in  libturret.h  is  the  structure  which  is  passed  to  any 
turrets  interface  function.  This  structure  is  a  union  of  structures  that  each  define  an  argument  list 
for  a  turrets  interface  function.  An  abbreviated  example  that  assumes  there  are  only  two  interface 
functions  is  shown  below.  Typically  there  will  be  more  interface  functions  and  therefore  more 
structure  definitions  in  the  union.  The  macros  hide  this  structure  from  the  users  of  these  functions. 


typsdsf  struct  turrets. interfacs 

{ 

union 

struct  turrets. set. azimuth 

{ 


float64  azimuth; 


Chapter  1:  Overview 


3 


>  ••t.azinuth; 

struct  turrets_set_aziBUth.spaed.aode 

{ 

float64  azisuth; 

float64  speed; 

TURRETS_SLEW.MODE.TYPE  mode; 

>  set.aziauth.speed.Bode; 

>  u; 

>  TURRETS. INTERFACE ; 

Issuing  a  command  to  an  objects’s  turret  component  is  done  by  invoking  one  of  the  macros 
defined  in  libturrets.  These  macros  identify  the  specific  component  function  which  needs  to  be 
called.  For  example,  invoking  the  TURRETS. SET. AZIMUTH  macro  will  result  in  the  calling  of  the 
set_a2imuth  specific  component  function.  In  the  public  header  file  of  each  generic  library,  macros 
are  associated  with  a  function  code  number  so  that  a  call  to  the  libcomponents  library  (via  the 
cmpntJnvoke  function)  will  dispatch  a  call  to  the  appropriate  function.  The  specific  component 
functions  are  defined  and  installed  by  the  specific  library  (libgenturret).  It  is  the  specific  function 
(libgenturret’s  set_azimuth)  which  is  called  when  the  macro  is  invoked. 

Invoking  the  macro  results  in  two  actions:  (1)  setting  up  of  the  interface  structure  and  (2) 
passing  of  necessary  information  to  libcomponent.  The  macro  passes  the  vehicle  id,  component 
number,  and  function  pointer  index  to  libcomponent  so  that  the  appropriate  library  (libgenturret) 
data  can  be  accessed.  The  requested  function  can  require  input  (such  as  an  azimuth  and  a  speed) 
and/or  output  (such  as  a  setting).  Therefore,  libcomponents  must  also  be  passed  the  address  of  the 
interface  structure  that  holds  this  data.  In  the  cmpnt_invoke(TURRETS_SET_AZIMUTH_FCll,  .vid, 
_cnua,  ( ADDRESS) t.t If ) ;  code  segment  shown  above,  TURRETS.SET_AZIMUTH.FCN  serves  as  the 
function  pointer  index,  .vid  provides  the  vehicle  id,  _cnua  provides  the  component  number,  and 
fc.tif  provides  the  address  for  the  function’s  argument  list. 
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2  Examples 


To  initialize  iibgenturret,  an  instance  of  the  turret  class  which  provides  for  up  to 
GENERIC_TURRET_MAX_TURRETS  turrets  per  entity: 

int32  i; 

char  buf [256] ; 

for  (i  -  0;  i  <  GENERIC.TURRET.MAX. TURRETS ;  i++) 

(void)  sprintf(buf,  "turretXd" ,  i) ; 
generic.turret.user.data.handle [i]  ■ 

claaa.raaerva.uaer.dataCparent.claaa,  buf,  generic.turret.print) ; 

> 

/*  Tell  libcomponents  we  are  available.  */ 

cmpnt.def ine_ instance (SM_GenericTurret ,  GENERIC. TURRET. MAX.TURRETS , 

generic. turrat.uaer. data. handle , 
generic. turret.create ,  generic.turret. destroy , 
TURRETS.SET_AZIMUTH.FCN,  set. azimuth, 
TURRETS.SET_AZIMUTH.SPEED_MODE.FCN , 
set.azinuth_8peed.mode , 
TURRETS_SET.AZIMUTH_CURVE_MODE.FCN, 
set_azimuth_curve.node) ; 


To  get  the  component  number  of  a  turret  with  a  particular  name  (such  as  "primary-turret"): 


int32  turret; 

if  ((turret  *  cmpnt_locate( vehicle. id,  name))  ■* 

CMPNT.NOT.FOUND) 

printf ("Vehicle  Xd  does  not  seem  to  have  a  turret  called  V'XsV  An" , 
vehicle. id, 
name) ; 

To  then  give  a  command  to  that  turret  (the  macro  is  defined  by  libturrets;  it  assembles  a 
TURRETS. INTERFACE  structure,  and  calls  cmpnt. invoke): 

if  (turret  !-  CMPNT.NOT.FOUND) 

TURRETS .SET. AZIMUTH (vehicle. id,  turret,  azimuth); 
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3  Functions 


The  following  sections  describe  each  function  provided  by  iibturrets,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


3.1  turrets-init 

void  turrets. ini t() 

turrets _init  initializes  Iibturrets.  Call  this  function  after  cmpnt.init,  and  before  any  specific 
turret  init  functions. 


3.2  TURRETS  .SET -AZIMUTH 

void  TURRETS_SET_AZIKUTH(_ vid ,  .cnua,  .azim) 
int32  .vid; 

int32  .cnum; 

float64  _azim; 

‘.vid’  Specifies  the  vehicle  ID 

‘.cnum’  Specifies  the  turret  component  number 

‘.azim’  Specifies  the  desired  azimuth  in  math  radians.  0  is  interpreted  as  pointing  out  the 
Y-axis  of  what  the  turret  is  attached  to,  and  rotation  is  positive  counter-clockwise. 

TURRETS.SET.AZIMUTH  sets  the  desired  azimuth  (in  vehicle  coordinates)  of  the  turret,  and  in¬ 
structs  the  turret  to  move  to  that  azimuth  in  an  optimal  way  for  target  tracking.  A  turret  will 
typically  only  be  able  to  move  to  this  azimuth  in  two  ticks  or  more  (this  is  because  DIS  has  entity 
articulations  with  speeds,  so  at  least  one  tick  must  be  consumed  updating  the  desired  slew  rate  in 
the  entity  appearance  PDU).  To  use  this  to  track  a  moving  target,  best  results  will  be  obtained 
by  specifying  a  projected  azimuth  for  two-ticks  into  the  future  (this  is  equivalent  to  "leading"  the 
gun). 


3.3  TURRETS J5ET -AZIM  U TH -SPEED _M ODE 
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void  TURRETS.SET.AZIMUTH.SPEED.MODEC.vid,  _cnum,  _&zim,  _ap,  .node) 
int32  _vid; 

int32  _cnua; 

float64  .azia; 

float64  _ap; 

TURRETS. SLEW.MODE. TYPE  .mod#; 

‘_vid’  Specifies  the  vehicle  ID 

‘.cnua’  Specifies  the  turret  component  number 

‘.azia’  Specifies  the  desired  azimuth  in  math  radians.  0  is  interpreted  as  pointing  out  the 
Y-axis  of  what  the  turret  is  attached  to  and  is  positive  counter-clockwise. 

‘_sp’  Specifies  a  speed  in  radians-per-second 
‘.mode’  Specifies  the  direction  of  travel  for  the  turret. 

TURRETS_SET.AZIMUTH.SPEED.MODE  sets  the  desired  azimuth  (in  vehicle  coordinates)  of  the 
turret,  the  maximum  speed  (in  radians  per  second)  to  get  to  that  azimuth,  and  the  way  to  slew 
the  turret  to  that  azimuth. 

The  .node  can  have  the  following  values: 

TURRETS.SLEW.MIHIMUM 

Move  the  turret  in  the  direction  that  will  get  to  the  desired  azimuth  fastest. 
TURRETS.SLEV.MAXIMUM 

Move  the  turret  in  the  direction  that  will  get  to  the  desired  azimuth  slowest.  If  the 
turret  is  not  fully  rotatable,  this  will  default  to  TURRETS.SLEW.MIHIMUM. 

TURRETS. SLEW.CLOCKWISE 

Move  the  turret  clockwise  to  the  desired  azimuth.  If  the  turret  is  not  fully  rotatable, 
this  will  default  to  TURRETS.SLEW.MIHIMUM. 

TURRETS.SLEW.COUNTERCLOCKWISE 

Move  the  turret  counterclockwise  to  the  desired  azimuth.  If  the  turret  is  not  fully 
rotatable,  this  will  default  to  TURRETS.SLEW.MIHIMUM. 


3.4  TURRETS  J5ET  _A  ZIM  U  TH  _CURVE_M  ODE 

void  TURRETS.SET. AZIMUTH. CUR VE.MODEC.vid ,  _cnum,  _azim,  _nent ,  _ents ,  .mode) 


int32 

_vid; 

int32 

.cnua; 

float64 

.azia; 

int32 

.nent ; 
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TURRETS.SLEV.CURVE.EJITRY  _ents[]  ; 

TURRETS. SLEW.MODE  .node; 

‘.vid’  Specifies  the  vehicle  ID 

‘.emus’  Specifies  the  turret  component  number 

‘.azin’  Specifies  the  desired  azimuth  in  math  radians.  0  is  interpreted  as  pointing  out  the 
Y-axis  of  what  the  turret  is  attached  to  and  is  positive  counter-clockwise. 

‘.nent’  Specifies  number  of  entries  in  the  slew  curve. 

‘.ants’  Specifies  an  array  of  slew  curve  entries. 

‘.nods’  Specifies  the  direction  of  travel  for  the  turret. 

TURRETS.SET. AZIMUTH. CUR VE.MODE  sets  the  desired  azimuth  (in  vehicle  coordinates)  of  the  tur¬ 
ret,  an  array  of  speeds  (in  radians  per  second)  to  get  to  that  azimuth,  and  the  way  to  slew  the  turret 
to  that  azimuth.  The  array  of  speeds  is  called  a  slew  curve.  A  slew  curve  is  a  way  of  describing  the 
slewing  process  towards  an  azimuth.  The  curve  is  defined  by  up  to  TURRETS.MAX.SLEV.CURVE.ENTRIES 
of  TURRETS.SLEW.CURVE.EHTRIES.  An  entry  is  specified  as  follows: 

typedsf  struct  turrets.slew.curve. entry 

float64  rang*; 
float64  rate; 

>  TURRETS.SLEW.CURVE. ENTRY ; 

Each  entry  specifies  the  slew  rate  to  use  if  the  turret  is  greater  than  the  specified  range  away 
from  the  desired  azimuth.  A  curve  is  described  by  an  array  of  entries,  and  the  range  field  must 
be  monotonically  decreasing  in  such  an  array.  When  choosing  a  slew  rate  from  an  array  of 
TURRETS.SLEW.CURVE.EHTRIES,  a  turret  will  choose  the  slew  rate  corresponding  to  the  largest 
range  that  is  less  than  the  range  of  the  current  azimuth  to  the  desired  azimuth.  The  chosen  rate 
may  be  adjusted  in  a  turret  dependent  manner  if  the  turret  only  supports  discrete  slew  rates. 

The  .node  can  have  the  following  values: 

TURRETS.SLEW.MIHIMUM 

Move  the  turret  in  the  direction  that  will  get  to  the  desired  azimuth  fastest. 

TURRETS. SLEW.MAXIMUM 

Move  the  turret  in  the  direction  that  will  get  to  the  desired  azimuth  slowest.  If  the 
turret  is  not  fully  rotatable,  this  will  default  to  TURRETS.SLEW.MINIMUM. 

TURRETS. SLEW.CLOCKWISE 

Move  the  turret  clockwise  to  the  desired  azimuth.  If  the  turret  is  not  fully  rotatable, 
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this  will  default  to  TURRETS.SLEV.MIMIMUM. 

TURRETS. SLEW.COUHTERCLOCKWISE 

Move  the  turret  counterclockwise  to  the  desired  azimuth.  If  the  turret  is  not  fully 
rotatable,  this  will  default  to  TURRETS.SLEW.HIHIMUM. 
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1  O  vervie w 


LibUActContact  is  a  unit  level  reactive  task  that  monitors  enemy  activity  and  reacts  to  contact. 
SM.UActionOnContact  constantly  checks  if  the  unit  is  under  fire  or  enemy  vehicles  are  spotted.  If 
either  of  those  requirements  are  met,  SM.UActionOnContact  reacts  by  executing  an  appropriate 
response.  The  reactions  that  are  currently  supported  are: 

‘Contact  Drill’ 

Transparent  Frame  with  a  SM.UTargeter  task. 

‘Action  Drill’ 

Opaque  Frame  with  a  SH.UAssault  task. 

‘Occupy  Position’ 

Opaque  Frame  with  a  SH.UPrepOepyPos  and  a  SM.UTargeter  task. 

‘No  Action’ 

Goes  back  to  monitoring  for  enemy  contact 

The  reaction  executed  depends  on  the  parameter  values  that  were  set  by  the  operator  in  the 
User  Interface. 

If  a  Contact  Drill  is  executed,  a  transparent  taskframe  with  a  SM.UTargeter  task  (see  section 
‘Libutargeter’  in  LibUTargeter  Programmer’s  Manual)  is  pushed.  The  unit  continues  to  execute 
the  primary  task  while  shooting  at  the  enemy. 

If  an  Action  Drill  is  executed,  an  opaque  taskframe  with  a  SM.UAssault  task  (see  section 
‘Libuassault’  in  LibUAssault  Programmer’s  Manual)  task  is  pushed.  The  SM_UActionOnContact 
task  creates  an  assault  objective  at  the  computed  enemy  location.  This  objective  is  passed  to  the 
assault  and  the  SM.UAasault  is  executed. 

If  a  Occupy  Position  is  executed,  an  opaque  taskframe  with  a  SH.UPrepOepyPos  task  (see  sec¬ 
tion  ‘Libupoccpos’  in  LibUPrepOcpyPos  Programmer’s  Manual)  and  a  SM_UTargeter  task.  The 
SM.UActionOnContact  task  creates  an  objective  facing  the  enemy  and  chooses  logical  target  refer¬ 
ence  points  with  the  engagement  area  trp  at  the  enemy  location.  These  parameters  are  passed  to 
the  SH.UPrepOepyPos  task. 

If  the  SM.UActionOnContact  reacts  to  enemy  activity  by  doing  nothing  it  goes  back  to  moni¬ 
toring  for  enemy  activity. 

The  SM.UActionOnContact  never  emU  until  the  taskframes  that  it  resides  in  is  destroyed,  but  it 
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does  go  back  to  the  monitoring  state  when  action  is  no  longer  required  (meaning  there  are  no  more 
enemies  in  sight).  The  SILUActionOnContact  is  the  spoasoringTask  for  the  reactive  taskframes 
listed  above.  This  means  the  SILUActionOnContact  remains  active  even  when  the  original  frame 
was  suspended.  The  reaction  can  then  be  easily  monitored  and  stopped  when  necessary.  Also,  if 
the  situation  has  changed  enough  to  cause  a  different  type  of  reaction,  SILUActionOnContact  will 
stop  the  current  reaction  and  start  the  appropriate  reactive  taskframe. 

Other  reactive  taskframes  can  be  added  by  searching  for  the  string  NEW. REACTION  and  adding 
the  appropriate  information. 

The  task  state  machine  is  written  using  the  AAFSM  format  which  is  translated  to  C  using  the 
‘fsm2ch’  utility  (see  section  ‘Overview1  in  LibTask  Programmer’s  Manual). 


1.1  Task  Parameters 


When  a  SILUActionOnContact  task  is  created  or  modified,  parameters  in  the  parameter  block 
of  the  task  data  structure  are  referenced.  The  parameters  are  described  by  the  following  structure: 


typedef  enun  uactcontact.action 

{ 

UACTCOITACT.ACTIOI.OCCUPY.POSITIOI , 
UACTCOITACT.ACTIOI.ACTIOM.DRILL, 
UACTCOITACT.ACTIQI.COITACT.DRILL , 

UACTCOHACT.ACTIOI.IOIE 

>  UACTCOITACT. ACnOI ; 

typedef  struct  uactcontact.paraaeters 

float64  engagement .range; 

float64  under.fire.eneay.threshold; 

UACTCOITACT.  ACnOV  under.fire.saall.enemy.action; 

UACTCOITACT.  ACnOI  under.fire.large.enemy.action; 

float64  not.under.f ire.enemy.threshold ; 

UACTCOITACT. ACTION  not.under.f ire.small. enemy. action; 

UACTCOITACT. ACTION  not.under.f ire.large.enemy.action; 

VTARGETER.FIRE.TECHNIQUE  fire. technique; 

VASSESS.FIRE.TYPE  fire.type; 

>  UACTCO NT ACT. PARAMETERS ; 


‘  engagement  _  range  ’ 

Specifies  the  range  at  which  the  unit  will  engage  with  the  enemy 
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‘under.f ire.eneay. threshold’ 

Specifies  the  threshold  of  vehicles  to  decide  whether  the  enemy  activity  is  considered 
large  or  small  while  under  fire.  While  under  fire,  if  there  are  more  vehicles  than 
the  threshold,  the  action  taken  is  specified  by  the  under.f  ire.large.eneay.action 
parameter.  While  under  fire,  if  there  are  less  vehicles  than  the  threshold,  the  action 
taken  is  specified  by  the  under.f ire. saall.eneay.action  parameter.  A  typical  value 
is  3  vehicles. 

‘under.f ire.eaall.eneay.action’ 

Specifies  the  action  to  take  if  the  number  of  vehicles  is  less  than  the  under.f  ire.eneny. threshold 
while  under  fire.  The  choices  are  an  Assault,  a  Contact  Drill  (UTargeter),  an  Occupy 
Position,  and  no  action. 

‘under. fire.large. enemy. act ion’ 

Specifies  the  action  to  take  if  the  number  of  vehicles  is  more  than  the  under.f  ire.enemy.threshol 
while  under  fire.  The  choices  are  are  an  Assault,  a  Contact  Drill  (UTargeter),  an  Oc¬ 
cupy  Position,  and  no  action. 

‘not.under.f  ire.eneny.  threshold’ 

Specifies  the  threshold  of  vehicles  to  decide  whether  the  enemy  activity  is  considered 
large  or  small  while  not  under  fire.  While  not  under  fire,  if  there  are  more  vehicles  than 
the  threshold,  the  action  taken  is  specified  by  the  not.under.f  ire.large.eneay.action 
parameter.  While  not  under  fire,  if  there  are  less  vehicles  than  the  threshold,  the  action 
taken  is  specified  by  the  not  _  unde  r_  f  ire.  snail  _  enemy _  act  ion  parameter.  A  typical 
value  is  3  vehicles. 

‘not.under.f  ire.eaall.eneay.action’ 

Specifies  the  action  to  take  if  the  number  of  vehicles  is  less  than  the  not.under.f  ire.enemy.thresi 
while  not  under  fire.  The  choices  are  an  Assault,  a  Contact  Drill  (UTargeter),  an  Oc¬ 
cupy  Position,  and  no  action. 

‘not.under.f ire.large.eneay.action’ 

Specifies  the  action  to  take  if  the  number  of  vehicles  is  more  than  the  not.under.f  ire.enemy.thre 
while  not  under  fire.  The  choices  are  am  Assault,  a  Contact  Drill  (UTargeter),  an  Oc¬ 
cupy  Position,  and  no  action. 

‘fire. technique’ 

Specifies  the  type  of  firing  method  to  use.  The  choices  are  simultaneous  and  alternating. 


‘fire.type’ 

Specifies  the  method  of  firing  at  the  enemy.  The  three  types  are  "Distributed  Fire", 
"Volley  Fire",  and  "None". 
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1.2  Parametric  Data 

The  parametric  data  for  SH.UictionOnContact  is  as  follows: 

‘speed’  Specifies  the  speed  at  which  to  conduct  a  reactive  assault. 

‘monitor.psriod’ 

Specifies  the  time  to  wait  before  monitoring  the  enemy  activity.  This  is  usually  about 
5000  milliseconds. 

‘under.f ire. time’ 

Specifies  the  time  after  receiving  fire  to  consider  the  unit  still  under  fire.  If  nobody 
in  the  unit  has  been  fired  upon  for  this  time,  the  unit  is  considered  not  under  fire.  A 
typical  value  is  10000  milliseconds. 

‘defens ible.pos i t ion.dist  ’ 

Specifies  the  distance  in  front  of  the  unit  leader  that  the  defensible  position  will  be  set 
up  in  a  reactive  occupy  position. 

‘def  ens ible.pos ition. width’ 

Specifies  the  width  of  the  defensible  position  for  a  reactive  occupy  position, 
‘trp.sector.depth’ 

Specifies  the  depth  at  which  to  locate  the  trps  for  a  reactive  occupy  position.  The 
depth  is  the  distance  out  from  the  platoon  leader  in  the  direction  of  the  enemy, 
‘trp.ssctor.width’ 

Specifies  the  width  of  the  trp  locations.  The  width  is  the  distance  between  the  two 
trps. 

‘rstrsat.spssd’ 

Specifies  the  speed  at  which  to  conduct  a  withdraw.  This  speed  is  generally  very  fast. 
Currently  withdraw  is  not  supported  as  a  reaction. 
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2  Functions 


The  following  sections  describe  each  function  provided  by  libuactcontact,  including  the  format 
and  meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  uactcontact  Jnit 


void  uactcontact.  initO 


uactcontact.init  initializes  libuactcontact.  Call  this  before  any  other  libuactcontact  function. 


2.2  uactcontact_class Jnit 

void  uactcontact.claas_init(parent_class) 

CLASS.PTR  parent.class ; 

‘parent.class’ 

Class  of  the  parent  (declared  with  class.declare.dass) 

uactcontact. dass.init  creates  a  handle  for  attaching  uactcontact  class  information  to  vehi¬ 
cles.  The  parent.class  will  likely  be  safobj .class. 


2.3  uactcontactucreate 


void  uactcontact.create(vehide.id,  params,  po.db,  ctdb) 
int32  vehicle. id; 

UACTCOmCT.PARAMETRIC.DATA  eparans; 

PO. DATABASE  *po_db; 

CTDB  *ctdb; 


‘vehide.id’ 

Specifies  the  vehicle  ID 
‘parana’  Specifies  initial  parameter  values 
‘po.db’  Specifies  the  PO  database  where  the  task  can  be  found 
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‘ctdb’  Specifies  the  terrain  database  currently  in  use 

uactcontact.create  creates  the  uactcontact  class  information  for  a  vehicle  and  attaches  it 
vehicle’s  block  of  libclass  user  data. 


2.4  uactcontact-destroy 

void  uactcont act. destroy ( vehicle. id) 
int  vehicle. id; 

‘vehicle. id’ 

Specifies  the  vehicle  ID 

uactcontact.destroy  frees  the  uactcontact  class  information  for  a  vehicle.  This  should  be 
called  before  freeing  the  class  user  data  with  claae.f  ree.user.data. 


2.5  uactcontact  Jn  it  .task  .state 

void  uactcontact.init.task.state(task,  state) 

TaskClasa  *task; 

TaakStateClaas  estate; 

‘task’  Specifies  a  pointer  to  the  task  class  object  to  be  initialized, 
‘state’  Returns  the  initialized  state 


Given  a  new  SM.UActionOnContact  task  that  is  about  to  be  created,  uactcontact_init.task.state 
initializes  the  model  size,  and  state  variables. 
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3  Algorithms 


There  are  four  reactions  that  can  take  place  as  a  result  of  enemy  contact.  One  of  three 
(Not  counting  "No  Action")  reactive  taskframes  (Contact  Drill,  Assault,  and  Occupy  Position) 
can  get  pushed  when  enemy  contact  is  detected.  Once  this  reactive  taskframe  gets  pushed,  the 
SM_UActionOnContact  that  pushed  it  becomes  the  sponsoringTask.  This  means  the  SM.UActionOnContact 
remains  active  and  can  monitor  and  stop  the  reactive  taskframe. 

The  SM.UAoeionOnContact  will  stop  the  reactive  taskframe  if  the  number  of  enemy  vehicles  has 
changed  to  be  out  of  the  range  that  caused  that  specific  reactive  taskframe  to  be  pushed. 

For  example: 


range:  0-3  reactive  t/f  pushed:  Contact  Drill 

range:  3  -  infinity  reactive  t/f  pushed:  Occupy  Position 

When  the  enemy  is  first  detected  only  two  vehicles  are  seen;  a  Contact 
Drill  is  then  pushed .  The  unit  will  continue  to  execute  a  contact 
drill  until  the  number  of  enemy  vehicles  has  reached  4.  At  that  time, 
the  contact  drill  will  be  stopped  and  the  actions  on  contact  will  go 
back  to  monitoring  state  and  then  immediately  spaen  an  Occupy 
Position. 

The  unit  will  continue  to  execute  the  Occupy  Position  until  the  number 
of  enemy  vehicles  drops  beloe  2  vehicles.  It  will  then  stop  the 
occupy  position  and  start  a  contact  drill. 


As  seen  from  the  example,  hysteresis  is  built  in  to  prevent  the  constant  toggling  between  occupy 
position  and  contact  drill  when  the  number  of  enemy  vehicles  hovers  around  the  threshold  (3 
vehicles). 

Also,  if  both  reactive  taskframes  were  specified  to  be  an  occupy  position,  the  actions  on  contact 
will  continue  to  run  the  same  taskframe  when  crossing  the  threshold.  This  is  done  to  eliminate 
unnecessary  starting  and  stopping. 

The  reactive  taskframe  that  gets  pushed  by  SM.UActionOnContact  can  be  overridden  by  select¬ 
ing  RESUME  SUSPENDED  MISSION  during  a  reaction.  This  will  stop  the  reaction  and  continue 
the  mission.  Also,  the  SM.UActionOnContact  task  will  not  respond  to  enemy  activity  until  a  new 
situation  (more  or  less  vehicles  causing  a  transition  to  a  different  range)  occurs. 
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1  O  verview 


Libuassault  implements  a  unit  level  task  which  assaults  an  objective.  There  are  two  ways  a 
SM.UAaaault  can  occur.  First,  a  SM.UAaaault  can  be  planned.  When  it  is  planned,  the  assault 
objective  is  entered  through  the  user  interface.  The  other  way  a  SM.UAaaault  can  occur  is  through 
a  reaction  to  enemy  activity.  In  this  case,  the  assault  objective  is  passed  in  as  the  enemy  location. 

Once  the  assault  objective  is  known,  the  route  to  the  objective  must  be  found.  If  the  user 
entered  the  route  through  the  user  interface,  that  route  is  chosen.  If  not,  a  route  is  generated 
which  links  the  current  position  to  the  assault  objective. 

At  this  point,  the  SM_UAaaault  task  directs  the  subordinates  to  follow  the  route  to  the  objective 
using  the  SM.UTraval  task  (see  section  ‘Libutravel’  in  LibUTraveling  Programmer’s  Manual).  The 
unit  is  also  shooting  at  the  enemy  while  traveling  toward  the  objective. 

Once  the  unit  reaches  the  objective  or  the  starting  unit  strength  has  dropped  below  a  certain 
percentage,  the  unit  will  conduct  a  SM.UPrepOcpyPos  task  (see  section  ‘Libupoccpos’  in  LibUpoc- 
cpos  Programmer’s  Manual).  The  SM_UAasault  computes  a  battle  position  based  on  the  direction 
from  the  original  position  to  the  assault  objective.  This  computed  battle  position  presumably  puts 
the  unit  with  it’s  back  to  the  orignal  position  and  front  to  the  enemy  location.  This  battle  posi¬ 
tion  is  passed  to  the  SM_UPr«pOcpyPos  task  which  finds  defensible  positions.  Once  these  positions 
are  secured,  the  SM_UAaaault  executes  a  SM.UOcpyPoa  task  (see  section  ‘Libuoccpos’  in  Libuocc- 
pos  Programmer’s  Manual).  The  SM_UAaaault  task  stays  in  the  occupy  position  state  until  told 
otherwise. 

The  task  state  machine  is  written  using  the  AAFSM  format  which  is  translated  to  C  using  the 
‘fao2ch’  utility  (see  section  ‘Overview’  in  LibTask  Programmer’s  Manual). 


1.1  Task  Parameters 


When  a  SM.UAaaault  task  is  created  or  modified,  parameters  in  the  parameter  block  of  the  task 
data  structure  are  referenced.  The  parameters  are  described  by  the  following  structure: 


typedef  enum  uassault. reason 

UASSAULT. REASON. PLANNED , 
UASSAULT.REASON. REACTIVE 
>  UASSAULT.REASON; 
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typedef  struct  uassault .parameters 

< 

ObjectID  objective; 

ObjectlD  route; 

uint32  padding 1 ; 

f loat64  speed ; 

float64  stop.assault.percent; 

float64  engagement. range; 

UASSAULT. REAS 0 N  uassault. reason; 

VASSESS.FIRE.TYPE  fire. type; 

>  UASSAULT.PARAMETERS ; 

'objective' 

Specifies  a  persistent  object  which  defines  the  assault  objective.  This  object  can  be  a 
point  object,  line  object,  or  a  text  object. 

‘route’  Specifies  a  persistent  object  which  defines  the  optional  route  to  the  objective.  The 
route  is  a  line  object. 

‘speed’  Specifies  the  speed  at  which  the  unit  will  be  moving  during  the  assault, 
‘stop.assault.percent’ 

Specifies  the  percentage  of  the  unit  that  must  be  killed  in  order  to  stop  the  assault. 

‘engagement.range’ 

Specifies  the  range  at  which  the  unit  will  engage  with  the  enemy 
‘uassault.reason’ 

Specifies  whether  the  assault  was  a  reaction  to  enemy  activity  or  a  planned  task. 

‘fire.typs’ 

Specifies  the  method  of  firing  at  the  enemy.  The  three  types  are  "Distributed  Fire", 
"Volley  Fire",  and  "None". 
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2  Functions 

The  following  sections  describe  each  function  provided  by  libuassault,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 

2.1  uassaultjnit 

void  u&s s suit _ ini t() 

uaasault.ini t  initializes  libuassault.  Call  this  before  any  other  libuassault  function. 


2.2  uassault_class Jnit 

void  uaaaault_daaa.init(parent_daaa) 

CLASS.PTR  parent .class ; 

‘parent.class’ 

Class  of  the  parent  (declared  with  claas.dedare.daBs) 

uassault.dasa.init  creates  a  handle  for  attaching  uassault  class  information  to  vehicles.  The 
parent.daaa  will  likely  be  aafobj.daaa. 


2.3  uassault_create 


void  uaaaault.createCvehicle.id,  parama,  po.db,  ctdb) 
int32  vehicle. id; 

UASSAULT. PARAMETRIC. DATA  *paraaa; 

P0_ DATABASE  * po.db; 

CTDB  *ctdb; 


‘vehicle. id’ 

Specifies  the  vehicle  ID 

‘parana'  Specifies  initial  parameter  values 

‘po.db1  Specifies  the  PO  database  where  the  task  can  be  found 
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‘ctdb’  Specifies  the  terrain  database  currently  in  use 

uaaaault. create  creates  the  uassault  class  information  for  a  vehicle  and  attaches  it  vehicle’s 
block  of  libclass  user  data. 


2.4  uassault_destroy 

void  uassault.destroy(vehicle.id) 
int  vehicle.id; 

‘vehicle.id’ 

Specifies  the  vehicle  ID 

uassault. destroy  frees  the  uassault  class  information  for  a  vehicle.  This  should  be  called 
before  freeing  the  class  user  data  with  class.free_user.data. 


2.5  uassault jnit.task^tate 


void  uassault.init_task_state(task,  state) 
TaskClass  *task; 

TaskStateClass  estate; 


’task’  Specifies  a  pointer  to  the  task  class  object  to  be  initialized, 
‘state’  Returns  the  initialized  state 


Given  a  new  SM_UAssault  task  that  is  about  to  be  created,  uassault_init.task_state  ini¬ 
tializes  the  model  size,  and  state  variables. 
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1  O  verv ie w 


Libuataint  implements  a  unit-level  task  which  controls  a  group  (currently  only  one)  of  vehicles 
performing  an  air-to-air  intercept  against  an  enemy.  The  task  state  machine  is  written  using  the 
AAFSM  format  which  is  translated  to  C  using  the  ‘f  sm2ch’  utility  (see  section  ‘Overview’  in  LibTask 
Programmer’s  Manual). 

Libuataint  depends  on  libvtakeoif,  libvataint,  libpo,  libvtab,  libclass,  libctdb,  libaccess,  libreader, 
and  libparmgr. 


1.1  Task  Parameters 


When  a  SM.UATAInt  task  is  created  or  modified,  parameters  in  the  parameter  block  of  the  task 
data  structure  are  referenced.  The  parameters  are  represented  in  the  task  data  structure  as  follows: 


typedef  struct  uataint.paraswters 

VehiclelD  target. id; 

uintlS  paddingl ; 

float64  target. bearing;  /•  radians  */ 

floated  target.range;  /*  meters  */ 

VATAirr.FIRELPERMISSIOI  fire .permits ion; 
int32  weapon. count; 

VATAIIT.WEAPOIS.EHABLED  weapons. enabled [VATAIHT.MAX.WEAPOHS] ; 
int32  crank; 

VATAIMT.DISEIGAGE. METHOD  disengage.method ; 
int32  padding2; 

floated  beam,  range; 

>  UATAIMT.PARAMETEHS ; 


‘target. id’ 

Specifies  the  id  of  the  vehicle  to  intercept. 

‘target.bearing’ 

Specifies  the  bearing  to  the  target  in  radians.  This  parameter  is  only  set  if  the  target  id 
is  not  known. 

‘target.range’ 

Specifies  the  range  to  the  target  in  meters.  This  parameter  is  only  set  if  the  targetjd 
is  not  known. 

‘fire.peraission’ 
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Specifies  the  fire  permission  (VATAINT_HOLD_FIRE,  VATAINT.FIR.E_AT .WILL)  to 
be  used  during  the  intercept. 

‘w«apon.count’ 

Specifies  the  number  of  weapons  in  the  weapons  jenabled  list. 

‘veapons.enabled’ 

Specifies  the  weapons  which  the  aircraft  is  allowed  to  shoot  during  the  intercept. 

’crank’  Specifies  whether  to  perform  a  crank  maneuver  after  each  shot  taken  during  the  inter¬ 
cept. 

‘di a  engage. aethod’ 

Specifies  how  the  aircraft  should  disengage  from  the  target  it  is  intercepting  if  it  does 
not  destroy  it.  This  can  take  the  values  VATAINTJNTERNAL,  VATAINTJvIERGE, 
and  VATAINTJBUGOUT.  If  it  is  set  to  VATAINTJNTERNAL,  the  disengage  method 
used  will  be  based  upon  air-to-air  intercept  tactics  taking  into  account  the  range  to  the 
target  and  whether  a  radar-guided  missile  is  in  flight.  If  it  is  set  to  VATAINTJ4ERGE, 
the  aircraft  will  always  go  to  the  merge  to  disengage.  If  it  is  set  to  VATAINT .BUGOUT, 
the  aircraft  will  always  bugout  (no  later  than  12  nm  from  the  target)  to  disengage. 
‘beaa.range’ 

Specifies  the  range  in  meters  at  which  the  aircraft  should  turn  into  the  enemy  target’s 
radar  beam. 
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2  Functions 

The  following  sections  describe  each  function  provided  by  libuataint,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  uataintJnit 

void  uataint.initO 

uataint.init  initializes  libuataint.  Call  this  before  any  other  libuataint  function. 


2.2  uataint^class _init 

void  uataint_class.ini t (parent.class) 

CLASS.PTR  parent. class; 

‘parent.class’ 

Class  of  the  parent  (declared  with  class.dedare.dass) 

uatalnt.class.init  creates  a  handle  for  attaching  uataint  class  information  to  vehicles.  The 
parent.class  will  likely  be  safobj.dass. 


2.3  uataint_create 

void  uataint.create (vehicle. id,  parans,  po.db,  ctdb) 
int32  vehicle. id; 

UATAIMT.PARAMETRIC.DATA  *parans; 

PO. DATABASE  * po.db; 

CTDB  *ctdb; 

‘vehide.id’ 

Specifies  the  vehicle  ID 

‘parans’  Specifies  initial  parameter  values 

‘po.db’  Specifies  the  PO  database  where  the  task  can  be  found 
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‘etdb’  Specifies  the  terrain  database  currently  in  use 

uataint. create  creates  the  uat&int  class  information  for  a  vehicle  and  attaches  it  vehicle’s 
block  of  libclass  user  data. 


2.4  uataintulestroy 

void  uataint.destroy(vehicle.id) 
int  vehicle. id; 

‘vehide.id’ 

Specifies  the  vehicle  ID 

uataint.destroy  frees  the  uataint  class  information  for  a  vehicle.  This  should  be  called  before 
freeing  the  class  user  data  with  claes.free.user.data. 


2.5  uataint Jnit_task_*tate 

void  uataint_init.task.state(task,  state) 

TaakClass  *task; 

TaskStateClass  estate; 

’task’  Specifies  a  pointer  to  the  task  class  object  to  be  initialized. 

‘state’  Returns  the  initialized  state 

Given  anew  SMLUATAint  task  that  is  about  to  be  created,  uataint. init_task_state  initializes 
the  model  size,  and  state  variables. 

» 
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1  O  vervie  w 

TEMPLATE:  Describe  what  this  library  does  here. 

1.1  Examples 

TEMPLATE:  Give  examples  here. 
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2  Fu  n  ctio  n  s 

The  following  sections  describe  each  function  provided  by  libuatgrndtrgt,  including  the  format 
and  meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 

TEMPLATE:  Adjust  alignment  of  descriptions 

TEMPLATE:  Correct  argument  lists  and  descriptions  of  these  functions. 


2.1  uatgtg_init 

void  uatgtg.initQ 

uatgtg_init  initializes  libuatgrndtrgt.  Call  this  before  any  other  libuatgrndtrgt  function. 


2.2  uatgtg jclass Jnit 

void  uatgtg.clasa.init (par ent.class) 

CLASS.PTR  parant.claaa ; 

‘parent. claaa’ 

Class  of  the  parent  (declared  with  claas.dadara.claaa) 

uatgtg.claaa.init  creates  a  handle  for  attaching  uatgrndtrgt  class  information  to  vehicles. 
The  parant.claaa  will  likely  be  aafobj  .class. 


2.3  uatgtg_create 


void  uatgtg_create(vehide_id,  params) 
int  vehicle. id; 

UATGRNDTRGT. PARAMETRI C _ D ATA  *params; 


‘vehide.id’ 

Specifies  the  vehicle  ID 
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‘par ana’  Specifies  initial  parameter  values 

uatgtg_create  creates  the  uatgrndtrgt  class  information  for  a  vehicle  and  attaches  it  vehicle’s 
block  of  libclass  user  data. 


2.4  uatgtg_deatroy 

void  uatgtg_destroy(vahicl«_id) 
int  vehicle.id; 

‘vehicle.id' 

Specifies  the  vehicle  ID 

uatgtg.destroy  frees  the  uatgrndtrgt  class  information  for  a  vehicle.  This  should  be  called 
before  freeing  the  class  user  data  with  claas_frea.usar.data. 
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1  O  verview 


Libubingofuel  implements  a  unit-level  task  which  controls  a  group  (currently  only  one)  of  vehicles 
detecting  that  they  have  reached  the  bingo  fuel  level  and  flying  to  and  landing  at  a  refueling  point. 
The  task  state  machine  is  written  using  the  AAFSM  format  which  is  translated  to  C  using  the 
‘fsm2ch’  utility  (see  section  ‘Overview’  in  LibTask  Programmer’s  Manual). 

Libubingofuel  depends  on  libvtab,  libclass,  libpo,  libctdb,  liburtb,  libaccess,  libreader,  and  lib- 
parmgr. 


1.1  Task  Parameters 


When  a  SM_Ubingofuel  task  is  created  or  modified,  parameters  in  the  parameter  block  of  the 
task  data  structure  are  referenced.  The  parameters  are  represented  in  the  task  data  structure  as 
follows: 


typedef  struct  ubingofuel.parameters 

ObjectID  base; 

uintl6  .padding; 

float64  speed; 

f loat64  altitude ; 

>  UBIVGOFUEL.PARAMETERS; 


‘base; ’  Specifies  the  bingo  refuel  base  for  the  plane  to  go  to. 

‘speed;’  Specifies  the  speed  for  the  plane  to  go  when  going  to  the  bingo  refuel  point, 

‘altitude;’ 

Specifies  the  altitude  for  the  plane  to  be  at  when  going  to  the  bingo  refuel  point. 
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2  Functions 

The  following  sections  describe  each  function  provided  by  libubingofuel,  including  the  format 
and  meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  ubfuelJnit 

void  ubfuel.initO 

ubfuel.init  initializes  libubingofuel.  Call  this  before  any  other  libubingofuel  function. 


2.2  ubfuel_class Jnit 

void  ubfuel_claee_init (parent. class) 

CLASS.PTR  p arent. class ; 

‘parent.class’ 

Class  of  the  parent  (declared  with  class. declass. class) 

ubfuel.class.init  creates  a  handle  for  attaching  ubingofuel  class  information  to  vehicles.  The 
parent.class  will  likely  be  safobj .class. 


2.3  ubfuel^create 

void  ubfuel.createC vehicle. id,  parans,  po.db,  ctdb) 
int32  vehicle. id; 

UBINGOFUEL.PARAMETRI C_  DATA  eparaas; 

PO.DATABASE  * po.db; 

CTDB  *ctdb; 

‘vehicle.id’ 

Specifies  the  vehicle  10 

‘params’  Specifies  initial  parameter  values 

‘po.db’  Specifies  the  PO  database  where  the  task  can  be  found 
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(ctdb’  Specifies  the  terrain  database  currently  in  use 

ubfuel. create  creates  the  ubingofuel  class  information  for  a  vehicle  and  attaches  it  vehicle’s 
block  of  libclass  user  data. 


2.4  ubfuel.jdestroy 

void  ubfuel.destroy (vehicle. id) 
int  vehicle.id; 

‘vehicle.id’ 

Specifies  the  vehicle  ID 

ubfuel.destroy  frees  the  ubingofuel  class  information  for  a  vehicle.  This  should  be  called 
before  freeing  the  class  user  data  with  claee.free.user.data. 


2.5  ubfuel Jnit_task_state 

void  ubfuel.init.task.etate(task,  state) 

TaskClaaa  *task; 

TaskStateClass  estate; 

‘task’  Specifies  a  pointer  to  the  task  class  object  to  be  initialized. 

‘state’  Returns  the  initialized  state 

Given  a  new  SM_UBingoFuel  task  that  is  about  to  be  created,  ubfuel.init.task.state  ini¬ 
tializes  the  model  size,  and  state  variables. 
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1  O  verview 


Libucap  implements  a  unit-level  task  which  controls  a  group  (currently  only  one)  of  vehicles 
performing  a  Combat  Air  Patrol  (CAP).  Its  parameters  include  a  location  at  which  to  perform 
the  CAP,  direction  to  orient  the  CAP,  length  of  CAP  legs,  speed  (for  both  the  inbound  and 
outbound  legs),  altitude,  and  radar  control  settings.  The  task  state  machine  is  written  using 
the  AAFSM  format  which  is  translated  to  C  using  the  ‘fsm2ch’  utility  (see  section  ‘Overview’  in 
LibTask  Programmer’s  Manual). 

Libucap  depends  on  libvtakeoff,  libvcap,  libvsearch,  libcomponents,  libpo,  libvtab,  libclass, 
libctdb,  libaccess,  libstatmon,  libeditor,  libtaskedit,  libreader,  libparmgr,  libhulls,  and  libtask. 


1.1  Task  Parameters 


When  a  SM_UCap  task  is  created  or  modified,  parameters  in  the  parameter  block  of  the  task  data 
structure  are  referenced.  The  parameters  are  described  by  the  following  structure: 


typedef  emus  ucap.vc.type 

UCAP_VC_PLUS_MIMUS_1600 , 
UCAP_VC.PLUS.1600, 
UCAP_VC.MIMUS.1600 
>  UCAP. VC.TYPE ; 


typedef  struct  ucap.paraaeters 
■C 


ObjectIO 

position; 

uintl6 

paddingl ; 

float64 

orientation; 

float64 

length_of .legs ; 

float64 

inbound_leg_speed ; 

float64 

outbound. leg_speed ; 

float64 

altitude; 

int32 

mode; 

UCAP. VC.TYPE 

vc; 

float64 

half .height ; 

float64 

half. width; 

float64 

range; 

int32 

use.location; 

int32 

padding2; 

float64 

interest_location[2] 

float64 

interest.azimuth; 
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float64  interest .elevation; 

>  UCAP. PARAMETERS ; 

‘position’ 

Specifies  a  persistent  object  which  defines  the  position  of  the  cap.  This  object  can  be 
a  point  or  a  text  object. 

‘orientation’ 

Specifies  the  orientation  of  the  C  A  Pom  the  position  specified  in  the  previous  parameter. 
‘length_of. legs’ 

The  length  of  the  leg  of  the  CAP 
‘inbound.leg.speed’ 

The  speed  of  the  aircraft  on  the  inbound  leg  of  the  CAP. 

‘outbound.leg_speed’ 

The  speed  of  the  aircraft  on  the  outbound  leg  of  the  CAP. 

‘altitude’ 

The  altitude  to  perform  the  CAP  at. 

‘node’  Radar  Search  mode,  either  track  while  scan  or  manual  or  auto. 

‘vc’  UCAP  radar  vc  type  unem 

‘half.height’ 

This  value  represents  half  of  the  height  of  the  desired  radar  scan  volume. 

‘half. width’ 

This  value  represents  half  of  the  width  of  the  desired  radar  scan  volume. 

‘range’  This  value  represents  the  range  of  the  desired  radar  scan  volume. 

‘use.location’ 

Represents  the  orientation  type  to  use  for  the  radar,  either  a  location  or  azimuth/elevation. 
‘interest.location[2]  ’ 

If  useJocation  is  set  to  location,  the  location  to  use  for  the  radar  scan  volume  center. 
This  is  an  X  Y  location  (array),  not  an  object. 

‘intsrest.azinuth’ 

If  useJocation  is  set  to  az/el,  the  azimuth  to  orient  the  radar  to. 

‘  intereat.elavat ion’ 

If  useJocation  is  set  to  az/el.  the  elevation  to  orient  the  radar  to. 
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2  Functions 


The  following  sections  describe  each  function  provided  by  libucap,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  ucapJnit 

void  ucap.initO 

ucap.init  initializes  libucap.  Call  this  before  any  other  libucap  function. 


2.2  ucap_class_init 

void  ucap.daas.init(parent.dass) 

CLASS. PTR  parent.clasa ; 

‘parent.claas’ 

Class  of  the  parent  (declared  with  dass.dedare.dass) 

ucap_claas.ini t  creates  a  handle  for  attaching  ucap  class  information  to  vehicles.  The  parent. class 
will  likely  be  safobj. class. 


2.3  ucap_create 


void  ucap.createCvehide.id,  par  sms ,  po.db,  ctdb) 
int  vehicle. id; 

UCAP.PARAHETRIC.DATA  *parans; 

PO. DATABASE  *po.db; 

CTDB  *ctdb; 


‘vehicle. id’ 

Specifies  the  vehicle  ID 

‘par ana’  Specifies  initial  parameter  values 

‘po.db’  Specifies  the  PO  database  where  the  task  can  be  found 
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‘ctdb’  Specifies  the  terrain  database  currently  in  use 

ucap.create  creates  the  ucap  class  information  for  a  vehicle  and  attaches  it  vehicle’s  block  of 
libdass  user  data. 


2.4  ucap_idestroy 

void  ueap.destroy(vehicle.id) 
int  vehicle.id; 

‘vehicle. id’ 

Specifies  the  vehicle  ID 

ucap.destroy  frees  the  ucap  class  information  for  a  vehicle.  This  should  be  called  before  freeing 
the  class  user  data  with  class.free.user.data. 


2.5  ucap  .in  it -task  .state 

void  ucap.init.ta8k.state(task,  state) 

TaskClass  etask; 

TaskStateClass  estate; 

‘task’  Specifies  a  pointer  to  the  task  class  object  to  be  initialized. 

‘state’  Returns  the  initialized  state 

Given  a  new  SH.UCAP  task  that  is  about  to  be  created,  ucap.init.task.state  initializes  the 
model  size,  and  state  variables. 
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1  Overview 


Libucommit  implements  a  unit-level  task  which  detects  when  a  group  (currently  only  one)  of 
vehicles  have  detected  a  radar  target  which  meets  the  commit  criteria.  It  creates  an  intercept  task 
frame  and  pushes  it  onto  the  unit’s  stack,  causing  the  unit  to  perform  an  air-to-air  intercept  on  the 
target.  The  task  state  machine  is  written  using  the  AAFSM  format  which  is  translated  to  C  using 
the  ‘fsa2ch’  utility  (see  section  ‘Overview’  in  LibTask  Programmer’s  Manual). 


1.1  Task  Parameters 

When  a  SM_UConit  task  is  created  or  modified,  parameters  in  the  parameter  block  of  the  task 
data  structure  are  referenced.  The  parameters  are  represented  in  the  task  data  structure  as  follows: 

typedef  struct  ucosadt.paraMters 

< 

float64  tgt .range. threshold; 

floated  tgt. aspect. threshold; 

floated  tgt. speed. threshold; 

VATAIHT.FIRE.PERMISSIOH  f ire.peraission; 
int32  weapon. count; 

VATAI IT_WEAPOIS.es ABLED  weapons.enabled [VATAIBT.MAI.WEAPOSS] ; 
uint32  crank; 

VATAIIT.DISEIGAGE. METHOD  disengage.nethod; 
floated  beaaLrange ; 

>  ucoesd.t. PARAMETERS ; 

All  of  the  first  three  thresholds  must  be  met  before  the  coanit  task  will  be  initiated. 

‘tgt. range,  threshold’ 

Specifies  the  maximum  range  between  vehicle  and  target  that  would  trigger  this  task, 
‘tgt.aspect.threshold’ 

Specifies  the  maximum  target  aspect  angle  (left  or  right)  that  would  cause  this  task  to 
trigger. 

‘tgt.spaed. threshold’ 

Specifies  the  minimum  speed  that  the  target  must  be  flying  in  order  to  trigger  this 
task. 

The  following  parameters  are  all  used  as  inputs  to  the  air  to  air  intercept  task. 
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‘fire.permiaaion’ 

Specifies  the  permission  to  pass  to  the  air  to  air  intercept  task.  The  choices  are 
VATAIIT.HOLD.FIRE  and  VATAINT.FIRE.  AT. WILL. 

‘v«apon_count’ 

Specifies  the  number  of  weapons  in  the  weapons  enabled  list. 

‘veapons.enabled’ 

Specifies  a  list  of  the  weapons  that  an  aircraft  is  allowed  to  shoot  during  an  air  to  air 
intercept  task. 

‘crank’  Specifies  whether  to  perform  a  crank  manuever  after  each  shot  taken  during  an  air  to 
air  intercept  task. 

‘disengage.nethod’ 

Specifies  how  the  aircraft  should  disengage  from  a  target  during  an  intercept  if  the 
target  was  not  destroyed.  The  possible  values  for  this  variable  are  VATAINT.INTERNAL, 
VATAIMT.MERGE,  and  VATAINT.BUGOUT. 

‘beam_ranga’ 

Specifies  the  range  in  meters  at  which  the  aircraft  should  turn  into  the  enemy  target’s 
radar  beam. 
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2  Functions 


The  following  sections  describe  each  function  provided  by  libucommit,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  ucommitJnit 

void  ucomait.initO 

ucoaait.init  initializes  libucommit.  Call  this  before  any  other  libucommit  function. 


2.2  ucommit_clas8 Jnit 

void  ucoanit.dass.init(paront_class) 

CLASS.PTR  parent.dass; 

‘parent. class’ 

Class  of  the  parent  (declared  with  class.declare.dass) 

uconsttit_claas.ini t  creates  a  handle  for  attaching  ucommit  class  information  to  vehicles.  The 
parent.dass  will  likely  be  safobj  .class. 


2.3  ucommitucreate 


void  ucoasdt.createC vehicle. id,  parans,  po.db) 
int32  vehicle. id; 

UC0NMIT.PAIIA11ETRZC.DATA  *parans; 

P0_ DATABASE  * po.db; 


‘vehicle.id’ 

Specifies  the  vehicle  ID 
‘paraas’  Specifies  initial  parameter  values 
‘po.db’  Specifies  the  PO  database  where  the  task  can  be  found 


4 


LibUCommit  Programmer’s  Guide 


ucoaait.create  creates  the  ucommit  class  information  for  a  vehicle  and  attaches  it  vehicle’s 
block  of  libclau  user  data. 


2.4  ucommit_destroy 

void  uconaait_destroy( vehicle. id) 
int  vehicle. id; 

‘vehicle.id’ 

Specifies  the  vehicle  ID 

ucoonit. destroy  frees  the  ucommit  class  information  for  a  vehicle.  This  should  be  called  before 
freeing  the  class  user  data  with  class.free.user.data. 


2.5  ucommit _init_task_state 

void  ucoastit.init.taak.state ( task ,  state) 

TaskClass  *task; 

TaskStateClass  estate; 

‘task’  Specifies  a  pointer  to  the  task  class  object  to  be  initialized. 

.  ‘state’  Returns  the  initialized  state 

Given  a  new  SM_UConmit  task  that  is  about  to  be  created,  ucomait.init. task. state  initializes 
the  model  size,  and  state  variables. 
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1  Overview 


Libudsmnt  implements  a  unit-level  task  which  dismounts  a  group  of  subordinate  DIs  from  a 
specified  IFV. 

When  the  IFV  is  selected  to  dismount  its  DIs,  the  initial  action  is  to  determine  if  that  IFV  is 
carrying  any  DIs.  If  there  are  DIs  to  dismount,  a  halt  task  issued  to  that  IFV. 

The  task  state  machine  is  written  using  the  AAFSM  format  which  is  translated  to  C  using  the 
‘f an2ch’  utility  (see  section  'Overview’  in  LibTask  Programmer’s  Manual). 


1.1  Task  Parameters 

When  a  SM.UDsmnt  task  is  created  or  modified,  parameters  in  the  parameter  block  of  the  task 
data  structure  are  referenced.  The  parameters  are  represented  in  the  task  data  structure  as  follows: 

typedef  struct  udsBnt.parameters 

int32  prep.var; 

>  UDSMJfT.  PARAMETERS ; 

‘prep.var’ 

Specifies  whether  the  task  is  a  placeholder  preparation  for  another  task  frame  (and 
therefore  should  end  immediately).  If  prep.var  is  FALSE,  the  task  will  never  end. 
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2  Fun  ctio  n  s 


The  following  sections  describe  each  function  provided  by  libudsmnt,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  udsmntjnit 

▼old  udannt.initO 

udsmnt.init  initializes  libudsmnt.  Call  this  before  any  other  libudsmnt  function. 


2.2  udsmnt^class Jnit 

▼old  udsnnt.clasa.init (parent.claas) 

CLASS.PTR  parent.claas; 

‘parent. class’ 

Class  of  the  parent  (declared  with  class.declare.clasa) 

udsnmt_class.ini t  creates  a  handle  for  attaching  udismount  class  information  to  vehicles.  The 
parent.claas  will  likely  be  safobj.dass. 


2.3  udsmnt_jcreate 

void  udsant. create (vehicle. id ,  par ana,  po.db,  ctdb) 
int32  vehicle.id; 

UDSMMT.PARAMETRIC.DATA  aparans; 

PO. DATABASE  * po.db; 

CTDB  *ctdb ; 

‘vehicle.id’ 

Specifies  the  vehicle  ID 
‘par ana’  Specifies  initial  parameter  values 

‘po.db’  Specifies  the  PO  database  where  the  task  can  be  found 
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‘ctdb’  Specifies  the  terrain  database  currently  in  use 

udsnnt.create  creates  the  udismount  class  information  for  a  vehicle  and  attaches  it  vehicle’s 
block  of  libclass  user  data. 


2.4  udsmnt_destroy 

void  udsmnt .destroy (vehicle. id) 
int  vehicle.id; 

‘vehicle. id’ 

Specifies  the  vehicle  ID 

udsant.destroy  frees  the  udismount  class  information  for  a  vehicle.  This  should  be  called 
before  freeing  the  class  user  data  with  class_free.user.data. 


2.5  udsmnt  unit -task  .state 


void  udsant_inlt_task_8tate(task,  state) 
TaskClass  *task; 

TaskStateClass  estate; 


‘task’  Specifies  a  pointer  to  the  task  class  object  to  be  initialized, 
‘state’  Returns  the  initialized  state 


Given  a  new  SH_UDsamt  task  that  is  about  to  be  created,  udsmnt.init.task.state  initializes 
the  model  size,  and  state  variables. 
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1  Overview 


Libuenemy  implements  a  unit  level  background  task  which  maintains  a  list  of  the  spotted  enemy 
vehicles  that  all  the  vehicles  of  the  unit  can  see.  This  is  done  by  looking  at  the  lists  of  each  of  the 
vehicle  level  SM_V£neBy  tasks  and  merging  the  lists. 

Libuenemy  also  provides  a  method  for  detecting  the  following: 

minefields 
incoming  artillery 
enemy  superiority 
high  casualties 
air  raids 

These  variables  are  put  in  the  state  and  are  accessed  by  registering  functions  with  the  uenemy. reaction,  ini 
function.  The  caller  of  this  function  provides  a  function  for  each  of  the  above  situations.  For  ex¬ 
ample,  there  will  be  a  incoming_artillery Junction  that  will  be  called  when  the  boolean  variable 
artillery  is  set. 

Since  these  variables  are  state  variables,  libuenemy  will  monitor  the  state  changes  using  callbacks 
and  call  the  appropriate  functions  when  the  state  changes. 
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2  Functions 


The  following  sections  describe  each  function  provided  by  libuenemy,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  uenemyJnit 

void  ueneny.initO 

ueneay.init  initializes  libuenemy.  Call  this  before  any  other  libuenemy  function. 


2.2  uenemy_clas8 Jnit 

void  ueneay.elass. init  (parent .class ) 

CLASS.PTR  parent.claas; 

‘parent.claas’ 

Class  of  the  parent  (declared  with  dass.dedare.dass) 

ueneny_claas.ini t  creates  a  handle  for  attaching  uenemy  class  information  to  vehicles.  The 
parent.claas  will  likely  be  safobj. class. 


2.3  uenemyjcreate 


void  ueneay.create  (vehide.id,  parents ,  po.db,  unit.entry) 
int  vehide.id; 

UEMEMY.PARAMETRIC.DATA  eparaas; 

PO. DATABASE  * po.db; 

PO.DB.EITRY  * unit. entry; 


‘vehide.id’ 

Specifies  the  vehicle  ID 

‘parens’  Specifies  initial  parameter  values 

‘po.db’  Specifies  the  po  database  for  use  for  the  vehicle  information. 
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‘unit.entry’ 

Specifies  the  persistent  object  database  entry  for  the  unit  that  this  uenemy  is  created 
for. 

ueneay.create  creates  the  uenemy  class  information  for  a  vehicle  and  attaches  it  vehicle’s  block 
of  libclass  user  data. 


2.4  uenemy-jdestroy 

void  ueneay .destroy (vehicle. id,  isjnigration) 
int32  vehicle. id; 
int32  ie.Bigration; 

’vehicle. id’ 

Specifies  the  vehicle  ID 

‘is.migration’ 

Specifies  that  the  destroy  is  due  to  migration 

ueneay.destroy  frees  the  uenemy  class  information  for  a  vehicle.  This  should  be  called  before 
freeing  the  class  user  data  with  class.free.user.data. 


2.5  init„task.Btate 

void  ueneay_init_task_state(task,  state) 

TaskClass  *task; 

TaskStateClass  estate; 

‘task’  Specifies  a  pointer  to  the  task  class  object  to  be  initialized. 

‘state’  Returns  the  initialized  state 

Given  a  new  SILUEnemy  task  that  is  about  to  be  created,  uenemy. init_task_state  initializes 
the  model  size,  and  state  variables. 


2.6  uenemy^et .spotted  Jrom  .state 
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int32  ueneny_get_spotted_from_atata(db,  task,  lies,  list) 


PO. DATABASE  *db; 

TaskClass  *task; 

UEXEMY.FILTER.LD  live; 
VTAB.LIST  list; 


‘db’  The  current  persistent  object  database. 

‘task’  This  unit’s  uenemy  task. 

‘live’  An  enum  of  defined  type  UENEMY_FILTER_LD  (live/dead),  which  is  one  of  the  follow¬ 

ing:  UENEMY  JILTEILLDjLIVE  -  list  live  vehicles  only  UENEMY_FILTER_LD_DEAD 
•  list  dead  vehicles  only  UENEM Y_FILTERJLD_ANY  -  don’t  filter  for  live  or  dead  sta¬ 
tus 

‘list’  The  VTABJLIST  for  the  seen  vehicle’s  to  be  added  to.  NOTE:  this  must  be  an  already 
existing  list. 

Fill  out  an  existing  VTAB  list  with  the  all  vehicles  the  unit  currently  can  see  that  pass  the  filter 
settings. 


2.7  uenemy -get  .number  .seen 

int32  ueneBj.get_nuaber_seen(db ,  task,  live) 

P0_ DATABASE  *db; 

TaskClass  *task; 

UEBEHY.FILTER.LD  live; 

‘db’  The  persistent  object  database  being  used. 

‘task’  This  unit’s  uenemy  task. 

‘live’  An  enum  of  defined  type  UENEM  Y_FILTEIt_LD  (live/dead),  which  is  one  of  the  follow¬ 

ing:  UENEMY_FILTER_LD_LIVE  -  list  live  vehicles  only  UENEMY_FILTER_LD_DEAD 
-  list  dead  vehicles  only  UENEM Y_FILTER_LD_ANY  -  don’t  filter  for  live  or  dead  sta¬ 
tus 

ueneBj.get.nuBber.seen  returns  the  number  of  vehicles  that  fit  the  parameters  specified  in 
the  function  call.  It  uses  the  enums  detailed  in  the  parameter  definitions  above  to  specify  what  you 
want  counted. 


2.8  uenemy  .get  ^closest -vehicle -position 
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▼old  ueneay.get.cloaest.vehicle.poaitionCdb,  teak,  live,  ay.poa,  hia.poa) 

P0_ DATABASE  *db; 

TaakClaaa  *taak; 

UEMEHY.FILTER.LD  live; 
float64  *»y.pos ; 

floated  *hia.poa ; 

The  persistent  object  database  being  used. 

This  unit’s  uenemy  task. 

An  enum  of  defined  type  UENEMY.FILTERJLD  (live/dead),  which  is  one  of  the  follow¬ 
ing:  UENEMY  JILTEILLD-LIVE  -  list  live  vehicles  only  UENEMY  JILTER_LD_DEAD 
•  list  dead  vehicles  only  UENEMY_FILTER_LD_ANY  -  don’t  filter  for  live  or  dead  sta¬ 
tus 

A  painter  to  an  two  dimensional  array  containing  this  unit’s  representative  position, 
or  the  position  that  the  closest  vehicle  to  is  desired. 

A  painter  to  a  two  dimensional  array  into  which  the  location  of  the  appropriate  vehicle 
location  is  placed.  If  no  appropriate  vehicle  is  found,  his_pos  is  filled  with  zeros. 

This  function  returns  the  position  of  the  closest  vehicle  that  fits  the  parameters  specified  in  the 
function  call.  See  either  the  texinfo  or  the  header  file  for  the  enums  available  for  use  for  specification 
to  this  function. 


‘db’ 

‘task’ 

‘live’ 


‘■y.poa’ 

‘hia.poa’ 


2.0  uenemy_get.center.jofjmass 

int32  ueneay.get.center_of_nasa(db,  taak,  live,  coaupoa) 

PO.DATABASE  *db; 

TaakClaaa  *taak; 

UEMEMT.FILTER.LD  live; 
f loat64  *com.pos ; 

‘db’  The  persistent  object  database  being  used. 

‘taak’  This  unit’s  uenemy  task. 

‘live’  An  enum  of  defined  type  UENEMY  -FILTERJLD  (live/dead),  which  is  one  of  the  follow¬ 

ing:  UENEMY  JILTEILXDJLIVE  -  list  live  vehicles  only  UENEMY_FILTER_LD_DEAD 
-  list  dead  vehicles  only  UENEMY_FILTERJLD_ANY  -  don’t  filter  for  live  or  dead  sta¬ 
tus 

‘com_poa’  A  pointer  to  a  two  dimensional  array  into  which  the  location  of  the  appropriate  vehicle 
location  is  placed.  If  no  appropriate  vehicle  is  found,  his.pos  is  filled  with  zeros. 
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This  function  returns  the  position  of  the  avg  center  of  mass  of  all  the  vehicles  that  the  unit 
currently  knows  about  that  pass  the  filter  settings  passed  in  in  the  parameters  to  the  function  call. 
It’s  return  value  will  be  the  number  of  sighted  vehicles  that  passed  the  filter. 


2.10  uenemy .reaction Jnit 

UEIIEMY.REACTIOI.CB.PARMS.PTR  ueneny.reactlon_init(po.db,  unit. entry, 

mine. function, arty.function, 
high_loss. function, 
super. enemy. f unction , 
air.raid. function,  uaer.data) 

PO.DATABASE  ♦po.db; 

PO.DB.EHTRY  ♦unit. entry ; 

void  ( ♦mine.f unction) ()  ; 

void  (♦arty.function) () ; 

void  (♦high.loss. function) () ; 

void  (♦euper.enemy.function) () ; 

void  (♦air.rmid.function) () ; 

ADDRESS  uaer.data; 

‘po.db’  The  persistent  object  database  being  used. 

‘unit.entry’ 

The  persistent  object  database  entry  for  the  unit  initializing  to  use  the  reaction  flags, 
‘mine.function’ 

The  function  passed  in  that  will  be  called  when  the  minefield  boolean  variable  in  the 
state  is  set.  This  function  will  be  called  every  time  the  state  object  changes  and  the 
minefield  boolean  variable  is  set. 

‘arty.function’ 

The  function  passed  in  that  will  be  called  when  the  artillery  boolean  variable  in  the 
state  is  set.  This  function  will  be  called  every  time  the  state  object  changes  and  the 
artillery  boolean  variable  is  set. 

‘high_loss.function’ 

The  function  passed  in  that  will  be  called  when  the  high  Jo6ses  boolean  variable  in  the 
state  is  set.  This  function  will  be  called  every  time  the  state  object  changes  and  the 
high  Josses  boolean  variable  is  set. 

‘super. enemy.f unction’ 

The  function  passed  in  that  will  be  called  when  the  enemy  .superiority  boolean  variable 
in  the  state  is  set.  This  function  will  be  called  every  time  the  state  object  changes  and 
the  enemyjsuperiority  boolean  variable  is  set. 
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‘arty.function’ 

The  function  passed  in  that  will  be  called  when  the  airraid  boolean  variable  in  the 
state  is  set.  This  function  will  be  called  every  time  the  state  object  changes  and  the 
air  .raid  boolean  variable  is  set. 

‘user.data’ 

The  data  that  is  passed  to  each  one  of  the  above  functions  when  called. 

This  function  returns  a  pointer  to  a  structure  that  contains  most  of  the  above  information. 
UEHEMY_REACnOV.CB.PARMS.PTR.  The  purpose  of  the  return  pointer  is  so  that  this  pointer  can  be 
passed  to  the  uenemy_reaction_done  function. 

This  function  will  register  to  a  object jehangedjevent.  Every  time  the  uenemy  state  object 
changes,  the  reaction  boolean  state  variables  are  checked.  For  every  boolean  variable  set,  the 
corresponding  function  is  called  and  passed  the  user_data. 


2.11  uenemyj’eactionjdone 

▼old  ueneay_reaction_done(params_ptr,  po.db) 

UEHEMY.REACnOH.CB_PARMS.PTR  parane.ptr; 

P0_ DATABASE  * po.db; 

‘ptr’  This  ptr  of  type  UEHEMY.REACnOH.CB_PARMS.PTR  is  passed  to  this  function.  This 
pointer  points  to  the  structure  that  needs  to  be  deallocated  in  this  function.  This 
pointer  is  also  the  return  value  for  the  ueneBj.reaction.init. 

’po.db’  The  persistent  object  database  being  used. 

The  purpose  of  this  function  is  to  unregister  the  object  changed  event  handler  and  to  deallocate 
the  memory  allocated  in  the  ueneny.reaction.init  function. 
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1  Overview 


Libuflwrte  implements  a  unit-level  task  which  controls  a  group  (currently  only  one)  of  vehicles 
following  a  route.  The  task  state  machine  is  written  using  the  AAFSM  format  which  is  translated 
to  C  using  the  ‘fsn2ch’  utility  (see  section  ‘Overview1  in  LibTask  Programmer’s  Manual). 

Libuflwrte  depends  on  libvtakeoff,  libvflwrte,  libvorbit,  libpo,  libvtab,  libclass,  libctdb,  libaccess, 
libreader,  and  libparmgr. 


1.1  Task  Parameters 


When  a  SM.UFlwRt®  task  is  created  or  modified,  parameters  in  the  parameter  block  of  the  task 
data  structure  are  referenced.  The  parameters  are  represented  in  the  task  data  structure  as  follows: 


typedef  struct  uflwrte.paraoeters 


Object 10 
intl6 
float64 
float64 

VFLWRTE.MOVE.TYPE 

int32 

int32 

UCAP.VC.TYPE 

float64 

float64 

float64 

int32 

int32 

float64 

float64 

float64 

>  UF  LWRTE_  PARAMETERS ; 


route; 
paddingl ; 
speed; 
altitude; 
move .type; 
padding?; 

■ode; 

vc; 

half .height ; 
half .width; 
range; 

use.location; 

padding3; 

interest_location[2] ; 
interest. aziauth ; 
interest. elevation; 


‘route’  Route  is  a  persistent  object  which  defines  a  route  to  be  followed.  This  object  can  be  a 
point  object,  line  object,  or  a  text  object. 

‘speed’  Specifies  the  speed  for  the  route. 

‘altitude’ 

Specifies  the  altitude  for  the  route. 

‘move.type’ 

Specifies  the  movement  type  which  can  be  one  of  the  following  values: 
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‘VFLHRTE.MQVE.LOW.LEVEL’ 

Follow  at  a  constant  altitude,  only  increasing  altitude  to  go  over  an  obstacle. 
‘VFLVRTE_MOVE_COHTOUR’ 

Follow  the  contour  of  the  earth. 

‘VFLWRTE_MOVE_MOE’ 

Nap  of  Earth  •  maintain  constant  altitude  agl,  veering  around  obstacles. 

‘mode’  Radar  Search  mode,  either  track  while  scan  or  manual  or  auto. 

‘vc’  UCAP  radar  vc  type  unem 

‘half .height’ 

This  value  represents  half  of  the  height  of  the  desired  radar  scan  volume. 

‘half.eidth’ 

This  value  represents  half  of  the  width  of  the  desired  radar  scan  volume. 

‘range’  This  value  represents  the  range  of  the  desired  radar  scan  volume. 

‘uee.location’ 

Represents  the  orientation  type  to  use  for  the  radar,  either  a  location  or  azimuth/elevation. 
‘  interest. location [2]  ’ 

If  usejocation  is  set  to  location,  the  location  to  use  for  the  radar  scan  volume  center. 
This  is  an  X  Y  location  (array),  not  an  object. 

‘  internet .azimuth’ 

If  usejocation  is  set  to  az/el,  the  azimuth  to  orient  the  radar  to. 

‘interest.elevation’ 

If  usejocation  is  set  to  az/el,  the  elevation  to  orient  the  radar  to. 
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2  Fun  ctio  n  s 


The  following  sections  describe  each  function  provided  by  libuflwrte,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  uflwrteJnit 

▼old  uflvrte.initO 

uf lvrte.init  initializes  libuflwrte.  Call  this  before  any  other  libuflwrte  function. 


2.2  uflwrte.class.init 

▼old  uf lwrt e_class_ ini t (parent. class) 

CLASS.PTR  parent.claaa; 

‘parent. class’ 

Class  of  the  parent  (declared  with  class.declare.dass) 

uf lwrt e_class.ini t  creates  a  handle  for  attaching  uflwrte  class  information  to  vehicles.  The 
parent.dass  will  likely  be  safobj. class. 


2.3  uflwrte_create 


▼old  uflvrte. create (vehicle. id,  paraas,  po.db,  ctdb) 
int32  vehicle. id; 

UFLWRTE.PARAMETRIC.DATA  eparaas; 

PO. DATABASE  * po.db; 

CTDB  *ctdb; 


‘vehicle. id’ 

Specifies  the  vehicle  11) 

‘paraas’  Specifies  initial  parameter  values 

‘po.db’  Specifies  the  PO  database  where  the  task  can  be  found 
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‘ctdb’  Specifies  the  terrain  database  currently  in  use 

uflwrte.create  creates  the  uflwrte  class  information  for  a  vehicle  and  attaches  it  vehicle's 
block  of  libdass  user  data. 


2.4  ufl wrte_destroy 

void  uflwrte.destroy(vehicle.id) 
int  vehicle. id; 

‘vehicle. id’ 

Specifies  the  vehicle  ID 

uflwrte.destroy  frees  the  uflwrte  class  information  for  a  vehicle.  This  should  be  called  before 
freeing  the  class  user  data  with  clasa.free.user.data. 


2.5  uflwrte  unit  .task  .state 

void  uf lwrte.init.task.state ( task ,  state) 

TaskClass  *task; 

TaskStateClass  estate; 

‘task’  Specifies  a  pointer  to  the  task  class  object  to  be  initialized. 

‘state’  Returns  the  initialized  state 

Given  a  new  SH_UFlvRte  task  that  is  about  to  be  created,  uflwrte. ini t.task.state  initializes 
the  model  size,  and  state  variables. 
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1  Overview 

) 


Libumoont  implements  a  unit-level  task  which  mounts  a  group  of  subordinate  DIs  onto  the 
doeest  friendly  IFV. 

When  the  subordinate  DIs  are  issued  a  mount  task,  the  initial  action  is  to  issue  a  halt  task  to 
those  DIs.  A  search  for  the  doeest  friendly  IFV  within  a  specified  range  follows.  If  an  IFV  is  found, 
a  halt  task  is  issued  to  the  IFV  and  the  DIs  begin  moving  towards  that  IFV  and  mounts  them 
upon  reaching  them. 

The  sts»  nachine  will  wait  for  all  subordinates  DIs  to  get  to  an  IFV  and  then  go  to  a  ended 
state. 

The  task  state  machine  is  written  using  the  AAFSM  format  which  is  translated  to  C  using  the 
‘fsa&ch’  utility  (see  section  'Overview’  in  LibTask  Programmer's  Manual). 


1.1  Talk  Parameters 

When  a  SM.UMount  task  is  created  or  modified,  parameters  in  the  parameter  block  of  the  task 
data  structure  are  referenced.  The  parameters  are  represented  in  the  task  data  structure  as  follows: 

typedef  struct  unount .par anet era 

{ 

int32  prep.var; 

>  UHOUMT. PARAMETERS; 

‘prep.var’ 

Specifies  whether  the  task  is  a  placeholder  preparation  for  another  task  frame  (and 
therefore  should  end  immediately).  If  prep.var  is  FALSE,  the  task  will  never  end. 
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2  Function! 


The  following  section*  describe  each  function  provided  by  libumount,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  umountJnit 
void  unount.initO 

uaount.init  initializes  libumount.  Call  this  before  any  other  libumount  function. 


2.2  umount^clnnnJnit 

void  mount_class.ini  t (parent.claas) 

CLASS. PTR  parent.claas ; 

‘parent.claas’ 

Class  of  the  parent  (declared  with  class.declare.dass) 

mount. dass.init  creates  a  handle  for  attaching  umount  class  information  to  vehicles.  The 
parent.claas  will  likely  be  safobj.dass. 


2.3  umountjcreate 

void  mount. create (vehicle.id,  parans,  po.db,  ctdb) 
int32  vehicle. id; 

UNODIT.PAHAllETRIC.Dm  vparana; 

P0 .DATABASE  epo.db; 

CTDB  *ctdb; 

‘vehide.id’ 

Specifies  the  vehicle  ID 

‘par ana’  Specifies  initial  parameter  values 

‘po.db’  Specifies  the  PO  database  where  the  task  can  be  found 
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‘ctdb’  Specifies  the  terrain  database  currently  in  use 

uaount.create  creates  the  umount  class  information  for  a  vehicle  and  attaches  it  vehicle’s  block 
of  libdass  user  data. 


2.4  umount^destroy 

▼old  uaount .destroy (vehicle. id) 
int32  vehicle. id; 

‘vehicle. id’ 

Specifies  the  vehicle  ID 

uaount. destroy  frees  the  umount  class  information  for  a  vehicle.  This  should  be  called  before 
freeing  the  class  user  data  with  class.f  ree.user.data. 


2.5  umountJnit-taskjitate 


void  uaount.init .task. state (task ,  state) 
TeskClass  *task; 

TaskStateClass  estate; 


‘task'  Specifies  a  pointer  to  the  task  class  object  to  be  initialized, 
‘state’  Returns  the  initialized  state 


Given  a  new  SH.UMount  task  that  is  about  to  be  created,  uaount.init.task.state  initializes 
the  model  size,  and  state  variables. 
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1  Overview 


LibUnitOrg  manages  unit  organization  information  within  the  context  of  the  SAF  simulation.  It 
tracks  both  the  task  organized  and  functionally  organized  superior  and  subordinate  relationships  of 
units,  in  order  to  provide  this  information  without  the  need  for  frequent  persistent  object  database 
queries. 

LibUnitOrg  also  tracks  changes  to  units  which  are  made  by  outside  sources  (such  as  the  GUI), 
and  updates  the  simulation  accordingly. 
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2  Functions 


The  following  sections  describe  each  function  provided  by  libunitorg,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  unitorg_init 

void  unitorg.  initO 

unitorg.init  initializes  libunitorg.  Call  this  before  any  other  libunitorg  function. 


2.2  unitorg.xlass.init 

void  unitorg.class.init (parent. class) 

CLASS.PTR  parent .class; 

(parent_class’ 

Specifies  the  parent  class  (probably  c2obj_  class) 

unitorg.class.init  creates  a  handle  for  attaching  unitorg  class  information  to  entries.  The 
parent-class  is  one  created  with  daasjdeclarejdass. 


2.3  unitorg^create 

void  unitorg. create (entry ,  db) 

PO.ro.EURT  *  entry; 

P0.DATAB1SE  *db; 

‘entry’  Specifies  the  unit  entry 

‘db’  Specifies  the  PO  database 

unitorg.create  creates  the  unitorg  class  information  for  a  entry  and  attaches  it  to  the  entry’s 
libdass  user  data.  If  the  passed  entry  is  not  objectClassUnit,  this  routine  will  simply  return. 
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2.4  unitorg^destroy 

▼old  unitorg_destroy(sntry) 

PO.DB.EBTRY  * entry ; 

‘entry’  Specifies  the  unit  entry 

unitorg.dsstroy  frees  the  unitorg  class  information  for  a  entry. 

2.5  unitorg^changed 

▼old  unitorg. changed (entry) 

PO.DB.EBTRY  * entry; 

‘entry’  Specifies  the  unit  entry 

unitorg.changed  updates  unit  in  response  to  a  libpo  object  jchanged  event. 


2.6  unitorg.get-context 


void  unitorg.get. content (entry,  task .organized, 

superior, 

peers,  n.peers,  naz. peers, 

subordinates ,  n.subordinat es ,  nax. subordinates) 

PO.DB.EBTRY  sentry; 

int32  task. organized; 

PO.DB.EITRY  sssuperior; 

PO.DB.EBTRY  speers  □ ; 
int32  sn.peers ; 

Int32  aax.peers; 

PO.DB.EBTRY  ssubordinates  □ ; 
int32  sn.subordinates ; 

int32  naz. subordinates ; 


‘entry’  Specifies  the  unit  entry 
‘taak.organized’ 

Specifies  whether  to  get  the  task  organized  or  functionally  organized  context,  True  or 
False. 
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‘superior’ 

Specifies  where  to  return  the  superior  unit 
‘peers’  Specifies  an  array  to  return  peer  units 
“n. peers’  Specifies  number  of  peers  returned 
‘nax.peers’ 

Specifies  maximun  number  of  peers  to  return 
‘subordinates’ 

Specifies  an  array  to  return  subordinate  units  ' 

‘n. subordlnat es  ’ 

Specifies  number  of  subordinates  returned 
‘nax.subordinates’ 

Specifies  maximun  number  of  subordinates  to  return 

unitorg_g*t_cont*xt  returns  the  superior,  peers  and  subordinates  of  a  unit.  Any  of  superior, 
peers,  or  subordinates  may  be  BULL,  in  which  case  no  units  for  that  category  will  be  returned.  If 
peers  or  subordinates  are  non-null,  then  those  arrays  must  be  large  enough  to  hold  aax.peers 
and  nax.subordinates,  respectively. 

If  task. organized  is  TRUE,  then  information  about  the  task  organized  hierarchy  will  be  returned. 
Otherwise,  information  about  the  functionally  organized  hierarchy  will  be  used. 

This  routine  is  much  more  efficient  at  retrieving  information  about  a  unit  hierarchy  than  do¬ 
ing  a  po.query_for_current.obj  acts,  (see  section  ‘pojqueryJorjcurrentjobjects’  in  LibPO  Pro¬ 
grammer’s  Manual)  since  the  hierarchy  information  is  maintained  and  updated  incrementally  by 
libUnitOrg. 


2.7  unitorg_get jroles 


int32  unit  orgeat  .roles  (entry,  nax.roles,  roles) 
PO.DB.EITRT  * entry; 
int32  nax.roles; 

PO.DB.EHRT  *roles  □ ; 


‘entry’  Specifies  the  unit  entry 
‘nax.roles’ 


‘roles’ 


Specifies  the  length  of  roles  array  used  to  return  role  information 
Returns  all  the  roles  that  the  entry  is  acting  as,  including  itself 
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unitorg.get.roles  returns  (by  reference)  all  the  unit  entries  that  a  unit  is  acting  as,  including 
itself.  This  information  is  derived  from  the  task-organized  unit  hierarchy.  A  unit  will  be  acting  in 
the  role  of  the  unit’s  superior  if  it  is  the  subordinate  of  that  superior  with  the  lowest  job  number 
(promotion  index).  This  relationship  can  be  recursive,  in  that  the  superior  may  also  be  acting 
in  the  role  of  the  superior’s  superior,  and  so  on.  The  number  of  roles  that  the  entry  is  acting  as 
(including  itself)  is  returned  by  this  routine. 

This  routine  is  much  more  efficient  at  retrieving  information  about  a  unit  hierarchy  than  do¬ 
ing  * po.query .for. current. objects,  (see  section  ‘pojquery_for_current-objects’  in  LibPO  Pro¬ 
grammer’s  Manual)  since  the  hierarchy  information  is  maintained  and  updated  incrementally  by 
UbUnitOrg. 


2.8  unitorg.get .responsible .unit 

PO.DB.EITRY  eunitorg-get  responsible .unit (entry) 

PO.DB.EITRY  * entry ; 

’entry’  Specifies  the  unit  entry 

unitorg.get_responsible.unit  returns  the  entry,  lowest  in  the  unit  hierarchy,  that  is  respon¬ 
sible  for  the  passed  in  entry.  For  example,  if  the  input  is  a  platoon  object,  the  return  value  will 
be  the  vehicle  acting  as  the  leader  of  the  platoon. 


2.9  unitorg^etucapable.vehicles 


int32  unitorg-get-capable-vehicles ( entry .  result,  aax,  capabilities_aask) 
PO.DB.EITRY  * entry; 

PO.ra.EITRY  *result  □ ; 

int32  aax; 

uint32  capabilities_aask; 


’entry’  Specifies  the  unit  entry 

’result’  Specifies  an  array  to  store  the  result  in. 

’aax’  Specifies  the  size  of  the  result  array. 

‘capabilities.nask’ 

Specifies  a  mask  of  capabilities  to  search  for  when  accumulating  vehicles. 
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unitorg^et.capable.vehicles  returns  the  non-unit  entries  subordinate  to  the  passed  in 
entry  into  the  result  array.  This  function  recursively  descends  the  factional  hierarchy  to  find  all 
the  non-unit  subordinates.  The  number  of  non-unit  subordinates  found  is  returned,  cap abilities .mask 
contains  the  capabilites  of  the  vehicles  to  be  included  in  the  query.  The  mask  will  contain  values 
such  as  SAFCapabilityMobility,  as  encoded  in  the  libPO  protocol  file  ‘p_po.h\  A  mask  of  0 
means  to  include  all  vehicles,  regardless  of  capability.  If  passed  an  entry  corresponding  to  a  vehicle, 
that  vehicle  may  be  returned,  if  it  has  the  required  capability. 


2.10  unitorg -initialize JS A F -capabilities 

void  unitorg. initialize.SAF. cap abilities (entry,  capabilities) 

P0.DB.EITRT  * entry; 
uint32  capabilities ; 

‘entry*  Specifies  the  unit  entry 
‘capabilities* 

Specifies  the  capabilities  of  the  unit,  as  specified  by  a  mask  of  SAFCapabilities  values 
defined  by  the  libPO  unitClass  object  (see  section  ‘Unit  Class’  in  LibPO  Programmer’s 
Manual). 

unitorg. initialize  SAF.capabilities  sets  an  entry’s  SAF  capabilities.  All  this  function 
does  is  to  modify  the  entry’s  PO. 


2.11  unitorg„updateJS  A  F  .capabilities 

void  unit org_update_SAF_capabilities (entry,  capabilities) 

P0.1O.EITRT  * entry; 
uint32  capabilities; 

‘entry’  Specifies  the  unit  entry 
‘capabilities’ 

Specifies  the  capabilities  of  the  unit,  as  specified  by  a  mask  of  SAFCapabilities  values 
defined  by  the  libPO  unitClass  object  (see  section  ‘Unit  Class’  in  LibPO  Programmer’s 
Manual). 

unitorg.set  SAF.capabilities  modifies  an  entry’s  SAF  capabilities.  This  is  only  valid  for 
entries  corresponding  to  vehicles,  as  superior  units  inherit  capabilities  from  their  subordinate  units. 
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This  routine  may  have  no  effect  when  a  vehicle  is  ju*t  created;  unitorg. initial Ize.SAF.capabiliti 
should  be  used  in  that  case. 
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3  Global  Variables 


The  sections  below  describe  the  global  variables  by  including  a  synopsis  and  a  description.  The 
global  variables  are  callback  events  which  will  be  fired  when  changes  to  the  unit  hierarchy  are  made. 
Each  event  can  be  handled  by  attaching  a  unitorg. changed. event  .handler,  as  described  below: 

void  unitorg. changed. event .handler (object,  user. data) 

P0.0B.nmtY  •object; 

ADDRESS  user. data; 

unitorg.  changed,  event  .handler  is  called  when  the  organization  hierarchy  of  a  unit  is  changed, 
object  will  contain  the  entry  of  the  unit  which  has  a  changed  superior. 


3.1  unitorgjtask-organised  .changed  .event 

extern  CALLBACX.EVEIT.PTR  unitorg. task.organized.changed.event ; 

unitorg.task_organized. changed. event  is  a  libcallback  event  which  can  be  accessed  after 
libunitorg  is  initialized.  Applications  may  attach  a  unitorg.  changed,  event  .handler  to  this  event 
via  (see  section  ‘callback  register  Jiandler *  in  LibCallback  Programmer’s  Manual).  This  event  will 
be  fired  when  the  task  organized  superior  for  a  unit  has  changed. 


3.2  unitorgJfunctionjorganised  .changed  .event 

extern  CALLBACX.EVEIT.PTlt  unitorg.function.organized.changed_event; 

unitorg.function_organized.changed_event  is  a  libcallback  event  which  can  be  accessed 
after  libunitorg  is  initialized.  Applications  may  attach  a  unitorg. changed.event.handler  to  this 
event  via  (see  section  ‘callback-register  Jiandler’  in  LibCallback  Programmer’s  Manual).  This  event 
will  be  fired  when  the  functionally  organized  superior  for  a  unit  has  changed. 


3.3  UNITORG.M  AX  .BREADTH 


The  macro  UVITORG.MAX.BREADTH  is  a  typical  maxmimum  number  of  direct  subordinates  in  a 
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unit.  This  Is  a  reasonable  number  to  use  as  a  max  for  the  arrays  in  usitorg.get. context  and 
uni.t0rg.4et.  capable,  vehicles. 
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1  O  verv ie w 


Libunits  manages  the  editing  of  unit  class  persistent  objects.  The  display  of  these  objects 
performed  via  libBGRDB  icons,  present). 
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2  Functions 


The  following  sections  describe  each  function  provided  by  libunits,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  unitsJnit 


void  units. init() 


units _init  initializes  libunits.  Call  this  function  before 


calling  any  other  libunits  functions. 


2.2  units-create-editor 


int32  units_create_editor(data_path,  reader.f lags ,  dialog.parent , 

gul,  tactnap,  tcc,  ctdb,  aap.erase.gc, 
sensitive,  ref resh.event ,  db,  select,  pvd,  addr) 
*data.path; 
reader.f lags ; 
dialog.parent ; 
gui; 

tactnap; 
tcc; 

*ctdb; 

nap.erase.gc ; 


char 

int32 

Widget 

SGUI.PTR 

TACTMIP.PTR 

COORD.TCC.PTR 

CTDB 

GC 


SISTVE.WIIDOW.PTR  sensitive; 
CALLBACK.EVEIT.PTR  ref resh.event ; 
PO. DATABASE  *db; 

SELECT.TOOL.PTR  select ; 

PVD.GOI.PTR  pvd; 

SinulationAddress  *addr; 


‘data.path’ 

Specifies  the  directory  where  data  files  are  expected 
‘reader, flags' 

Specifies  flags  to  be  passed  to  reader.read  when  reading  data  files 
‘dialog.parent’ 

Specifies  top-level  shell  which  should  parent  popup  dialogs 
‘gui’  Specifies  the  SAF  GUI 
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*pvd’ 

Specifies 

‘tactaap’ 

Specifies 

‘tcc’ 

Specifies 

‘ctdb’ 

Specifies 

‘aap.erase.gc’ 

Specifies 

‘sensitive’ 

Specifies 

‘refresh. 

event’ 

Specifies 

‘db’ 

Specifies 

‘select’ 

Specifies 

♦pvd’ 

Specifies 

‘addr’ 

Specifies 

the  PVD 

the  tactical  map 

the  map  coordinate  system 

the  terrain  database 

the  GC  which  can  erase  things  from  the  tactical  map 

the  sensitive  window  for  the  tactical  map 

the  event  which  fires  when  the  map  is  refreshed 
the  persistent  object  database 
the  select  tool 
the  PVD  GUI 

the  Simulation  address  of  the  workstation 


units.create.editor  creates  the  units  editor.  The  data  file  (‘units. rdr’)  is  read  either  from 
‘.’or  the  specified  data  path,  depending  upon  the  reader.flaga.  The  reader.flags  are  as  in 
reader  .read.  The  return  value  is  zero  if  the  read  succeeds,  or  one  of  the  libreader  return  values: 
READER.READ.ERROR,  READER.FILE_iOT.FOUID. 


2.3  units  .class  Jnit 

void  units.class.init (parent. class) 

CLASS.PTR  parent. class; 

‘parent. class’ 

Specifies  the  parent  class  (probably  c2obj. class) 

units.class.init  creates  a  handle  for  attaching  units  class  information  to  entries.  The 
parent.dass  is  one  created  with  class.declare.dass. 


2.4  units^create 


void  units.create(entry) 
PO.SB.EITRY  * entry; 
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‘entry’  Specifies  the  unit  entry 

units.create  creates  the  units  class  information  for  a  entry  and  attaches  it  to  the  entry’s 
libdass  user  data. 

2.5  units_destroy 

▼old  units .destroy (entry) 

PO.DB.EITRY  * entry; 

‘entry’  Specifies  the  unit  entry 

units.destroy  frees  the  units  class  information  for  a  entry. 

2.6  units-changed 

▼oid  units.changod(entry) 

PO.DB.EITRY  * entry ; 

‘entry’  Specifies  the  unit  entry 

units. changed  updates  displayed  graphic  in  response  to  a  libpo  object. changed  event. 
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2  Functions 


The  following  sections  describe  each  function  provided  by  libunitutil,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  unitutil_create 


PO_DB_EITRY  *unitutil_create(nev,  db) 
UUTIL.UMIT.PARAMS  *new; 

PO. DATABASE  *db; 


unitutil. create  creates  a  unit  from  the  attributes  passed  in  the  new  UUTIL_UMIT_PARAMs 
argument  in  the  PO.DATABASE  identified  by  the  db  argument.  All  appropriate  subunits  are  created 
automatically.  A  pointer  to  the  unit’s  PO.DB.EKTRY  is  returned. 
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1  O  verv ie w 


Libuoecpoe  implements  a  unit-level  Occupy  Position  task.  The  Preparatory  task  (see  section 
‘Overview’  in  Libupoccpos  Programmer’s  Manual),  gets  the  subordinates  in  covered  positions.  The 
Occupy  Position  task  keeps  the  subordinates  in  these  positions  until  different  orders  are  assigned. 
The  task  state  machine  is  written  using  the  AAFSM  format  which  is  translated  to  C  using  the 
*fsa2ch’  utility  (see  section  ‘Overview’  in  LibTask  Programmer’s  Manual). 


1.1  Task  Parameters 

There  are  no  parameters  in  the  SM.UOcpyPoe  task. 
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2  Functions 


The  following  sections  describe  each  function  provided  by  libuoccpos,  including  the  format  and 
meaning  of  its  arguments,  and  the  meaning  of  its  return  values  (if  any). 


2.1  uoccpos-init 

void  uoccpos.  initO 

uoccpos.init  initializes  libuoccpos.  Call  this  before  any  other  libuoccpos  function. 


2.2  uoccpos_class_init 

void  uoccpos.class.init (parent. class) 

CLASS.PTR  parent. class; 

‘parent. class’ 

Class  of  the  parent  (declared  with  class.declaro.class) 

uoccpos.class.init  creates  a  handle  for  attaching  uoccpos  class  information  to  vehicles.  The 
parent  .class  will  likely  be  safobj  .class. 


2.S  uoccpos-create 


void  uoccpos.create (vehicle. id,  parane) 
int32  vehicle. id; 

UOCCPOS.PilUNETRIC.DATA  vparaas; 


‘vehicle. id’ 

Specifies  the  vehicle  ID 

‘paraas’  Specifies  initial  parameter  values 


uoccpos.create  creates  the  uoccpos  class  information  for  a  vehicle  and  attaches  it  vehicle’s 
block  of  libdass  user  data. 
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2.4  uoccpos-destroy 

void  uoccpoa.destroyC vehicle. id) 
int  vehicle. id; 

‘vehicle. id’ 

Specifies  the  vehicle  ID 

uoc epos _ destroy  frees  the  uoccpos  class  information  for  a  vehicle.  This  should  be  called  before 
freeing  the  class  user  data  with  class.f  ree.ua er.data. 


2.5  uoccpos Jnit_task-state 


void  U0ccpos_init.task.state(task,  state) 
TaskClass  *task; 

TaskStateClass  estate; 


‘task’  Specifies  a  pointer  to  the  task  class  object  to  be  initialized, 
‘state’  Returns  the  initialized  state 


Given  a  new  SMJJOcpyPoa  task  that  is  about  to  be  created,  uoccpos_init.task.state  initial¬ 
izes  the  model  size,  and  state  variables. 


